health.clients.fhir
Module health.clients.fhir
API
Declarations

ballerinax/health.clients.fhir Ballerina library
Package containing a generic FHIR client connector that can be used to connect to a FHIR server.
Package overview
This package is used to connect to a FHIR server using the FHIRConnector.
Compatibility
Version | |
---|---|
REST API Specification | https://hl7.org/fhir/http.html |
Bulk Data Export IG | https://hl7.org/fhir/uv/bulkdata/export.html |
Features and Capabilities
- Connects to a FHIR server that supports any widely used authentication mechanism. Eg: Oauth2, basic auth, etc.
- Support for all the FHIR interactions mentioned in the above specification.
- Support for all the FHIR bulk data export operations.
- Handle authentication to the server.
- Caching and managing the access tokens.
- Support for both FHIR+JSON and FHIR+XML payloads.
- Rewrite FHIR server URL in the response payload and headers with a custom URL.
Functions
extractResourceType
Extracts the resource type from the given payload.
handleError
Creates an HTTP response with an operation outcome error.
Parameters
- msg string - Error message to populate the operation outcome
- statusCode int (default http:STATUS_INTERNAL_SERVER_ERROR) - HTTP status code to be set in the response
Return Type
- Response - The HTTP response with the operation outcome error
handleResponse
function handleResponse(FHIRResponse|FHIRError fhirResponse) returns Response
Creates an HTTP response from the given FHIRResponse.
Parameters
- fhirResponse FHIRResponse|FHIRError - FHIR response to be converted to HTTP response
Return Type
- Response - The HTTP response
waitForBulkExportCompletion
function waitForBulkExportCompletion(string exportId)
Waits for the completion of a bulk export file download.
This function continuously checks the status of a bulk export task identified by taskId
.
It blocks execution until the export task status is "Downloaded", indicating the file download is complete.
Parameters
- exportId string - The unique identifier of the export task to monitor.
Clients
health.clients.fhir: FHIRConnector
This connector allows you to connect and interact with any FHIR server
Constructor
Initializes the FHIR client connector
init (FHIRConnectorConfig connectorConfig, boolean enableCapabilityStatementValidation)
- connectorConfig FHIRConnectorConfig - FHIR connector configurations
- enableCapabilityStatementValidation boolean true - Whether to validate the capability statement of the server
getById
function getById(ResourceType|string 'type, string id, MimeType? returnMimeType, SummaryType? summary) returns FHIRResponse|FHIRError
Retrieves a FHIR Resource by the resource logical ID
Parameters
- 'type ResourceType|string - The name of the resource type
- id string - The logical id of the resource
- returnMimeType MimeType? (default ()) - The MIME type of the response
- summary SummaryType? (default ()) - The subset of the resource content to be returned
Return Type
- FHIRResponse|FHIRError - If successful, FhirResponse record else FhirError record
getByVersion
function getByVersion(ResourceType|string 'type, string id, string 'version, MimeType? returnMimeType, SummaryType? summary) returns FHIRResponse|FHIRError
Retrieves a version specific FHIR resource
Parameters
- 'type ResourceType|string - The name of the resource type
- id string - The logical id of the resource
- 'version string - the version id
- returnMimeType MimeType? (default ()) - The MIME type of the response
- summary SummaryType? (default ()) - The subset of the resource content to be returned
Return Type
- FHIRResponse|FHIRError - If successful, FhirResponse record else FhirError record
update
function update(json|xml data, OnCondition? onCondition, MimeType? returnMimeType, PreferenceType returnPreference) returns FHIRResponse|FHIRError
Updates an existing resource or creates a new resource if the resource doesn't exists
Parameters
- data json|xml - Resource data
- onCondition OnCondition? (default ()) - Condition for a conditional update operation.
- To perform a conditional update, you can:
- Provide the conditional URL directly as a string (e.g.,
"identifier=12345&status=active"
). - Or, provide conditional parameters as a
SearchParameters
ormap<string[]>
, which will be used to construct the conditional URL. - If not specified, a normal update is performed.
- returnMimeType MimeType? (default ()) - The MIME type of the response
- returnPreference PreferenceType (default MINIMAL) - To specify the content of the return response
Return Type
- FHIRResponse|FHIRError - If successful, FhirResponse record else FhirError record
patch
function patch(ResourceType|string 'type, json|xml data, string id, OnCondition? onCondition, MimeType? returnMimeType, MimeType|PatchContentType? patchContentType, PreferenceType returnPreference) returns FHIRResponse|FHIRError
Partially Updates an existing resource
Parameters
- 'type ResourceType|string - The name of the resource type
- data json|xml - Resource data
- id string - The logical id of the resource
- onCondition OnCondition? (default ()) - Condition for a conditional patch operation.
- To perform a conditional patch, you can:
- Provide the conditional URL directly as a string (e.g.,
"identifier=12345&status=active"
). - Or, provide conditional parameters as a
SearchParameters
, ormap<string[]>
, which will be used to construct the conditional URL. - If not specified, a normal patch is performed.
- returnMimeType MimeType? (default ()) - The MIME type of the response
- patchContentType MimeType|PatchContentType? (default ()) - Content type of the patch payload
- returnPreference PreferenceType (default MINIMAL) - To specify the content of the return response
Return Type
- FHIRResponse|FHIRError - If successful, FhirResponse record else FhirError record
delete
function delete(ResourceType|string 'type, string id, OnCondition? onCondition) returns FHIRResponse|FHIRError
Deletes an existing resource.
Parameters
- 'type ResourceType|string - The name of the resource type
- id string - The logical id of the resource
- onCondition OnCondition? (default ()) - Condition for a conditional delete operation.
- To perform a conditional delete, you can:
- Provide the conditional URL directly as a string (e.g.,
"identifier=12345&status=active"
). - Or, provide conditional parameters as a
SearchParameters
, ormap<string[]>
, which will be used to construct the conditional URL. - If not specified, a normal delete is performed.
Return Type
- FHIRResponse|FHIRError - If successful, FhirResponse record else FhirError record
getInstanceHistory
function getInstanceHistory(ResourceType|string 'type, string id, HistorySearchParameters parameters, MimeType? returnMimeType) returns FHIRResponse|FHIRError
Retrieves the change history of particular resource
Parameters
- 'type ResourceType|string - The name of the resource type
- id string - The logical id of the resource
- parameters HistorySearchParameters (default {}) - The history search parameters
- returnMimeType MimeType? (default ()) - The MIME type of the response
Return Type
- FHIRResponse|FHIRError - If successful, FhirResponse record else FhirError record
create
function create(json|xml data, OnCondition? onCondition, MimeType? returnMimeType, PreferenceType returnPreference) returns FHIRResponse|FHIRError
Creates a new resource
Parameters
- data json|xml - Resource data
- onCondition OnCondition? (default ()) - Condition for a conditional create operation.
- To perform a conditional create, you can:
- Provide the conditional URL directly as a string (e.g.,
"identifier=12345&status=active"
). - Or, provide conditional parameters as a
SearchParameters
, ormap<string[]>
, which will be used to construct the conditional URL. - If not specified, a normal create is performed.
- returnMimeType MimeType? (default ()) - The MIME type of the response
- returnPreference PreferenceType (default MINIMAL) - To specify the content of the return response
Return Type
- FHIRResponse|FHIRError - If successful, FhirResponse record else FhirError record
search
function search(ResourceType|string 'type, RequestMode mode, SearchParameters|map<string[]>? searchParameters, MimeType? returnMimeType) returns FHIRResponse|FHIRError
Searches all resources of a particular type
Parameters
- 'type ResourceType|string - The name of the resource type
- mode RequestMode (default GET) - The request mode, GET or POST
- searchParameters SearchParameters|map<string[]>? (default ()) - The search parameters
- returnMimeType MimeType? (default ()) - The MIME type of the response
Return Type
- FHIRResponse|FHIRError - If successful, FhirResponse record else FhirError record
getHistory
function getHistory(ResourceType|string 'type, HistorySearchParameters parameters, MimeType? returnMimeType) returns FHIRResponse|FHIRError
Retrieves the change history of a particular resource type.
Parameters
- 'type ResourceType|string - The name of the resource type
- parameters HistorySearchParameters (default {}) - The history search parameters
- returnMimeType MimeType? (default ()) - The MIME type of the response
Return Type
- FHIRResponse|FHIRError - If successful, FhirResponse record else FhirError record
getConformance
function getConformance(ModeType mode, MimeType? returnMimeType, map<anydata>? uriParameters) returns FHIRResponse|FHIRError
Retrieves information about the server capabilities
Parameters
- mode ModeType (default FULL) - The information type required from the server
- returnMimeType MimeType? (default ()) - The MIME type of the response
- uriParameters map<anydata>? (default ()) - The additional parameters like _summary, _elements, refer the server capabilities
Return Type
- FHIRResponse|FHIRError - If successful, FhirResponse record else FhirError record
getAllHistory
function getAllHistory(HistorySearchParameters parameters, MimeType? returnMimeType) returns FHIRResponse|FHIRError
Retrieves the change history for all resources supported by the server.
Parameters
- parameters HistorySearchParameters (default {}) - The history search parameters
- returnMimeType MimeType? (default ()) - The MIME type of the response
Return Type
- FHIRResponse|FHIRError - If successful, FhirResponse record else FhirError record
searchAll
function searchAll(SearchParameters|map<string[]> searchParameters, RequestMode mode, MimeType? returnMimeType) returns FHIRResponse|FHIRError
Searches across all resources types
Parameters
- searchParameters SearchParameters|map<string[]> - The search parameters that are common across all resources
- mode RequestMode (default GET) - The request mode, GET or POST
- returnMimeType MimeType? (default ()) - The MIME type of the response
Return Type
- FHIRResponse|FHIRError - If successful, FhirResponse record else FhirError record
batchRequest
function batchRequest(json|xml data, MimeType? returnMimeType) returns FHIRResponse|FHIRError
Submits a set of actions to perform on a server in a single request, actions will be performed independently as a batch
Parameters
- data json|xml - Resource data
- returnMimeType MimeType? (default ()) - The MIME type of the response
Return Type
- FHIRResponse|FHIRError - If successful, FhirResponse record else FhirError record
'transaction
function 'transaction(json|xml data, MimeType? returnMimeType) returns FHIRResponse|FHIRError
Submits a set of actions to perform on a server in a single request,actions will be performed as a single atomic transaction
Parameters
- data json|xml - Resource data
- returnMimeType MimeType? (default ()) - The MIME type of the response
Return Type
- FHIRResponse|FHIRError - If successful, FhirResponse record else FhirError record
nextBundle
function nextBundle(FHIRResponse|json|xml currentBundle) returns FHIRResponse|FHIRError?
Provides support to paginate through resources where applicable(ex: History, Search related bundle resources), retrieves the next bundle if it exists
Parameters
- currentBundle FHIRResponse|json|xml - Current bundle resource should be generated as a result of invoking a connector method. This is to ensure consistency of urlRewrite feature. If the urlRewrite is enabled, the current bundles' urls should be rewritten.
Return Type
- FHIRResponse|FHIRError? - If successful, FhirResponse record else FhirError record
previousBundle
function previousBundle(FHIRResponse|json|xml currentBundle) returns FHIRResponse|FHIRError?
Provides support to paginate through resources where applicable(ex: History, Search related bundle resources), retrieves the previous bundle if it exists
Parameters
- currentBundle FHIRResponse|json|xml - Current bundle resource should be generated as a result of invoking a connector method. This is to ensure consistency of urlRewrite feature. If the urlRewrite is enabled, the current bundles' urls should be rewritten.
Return Type
- FHIRResponse|FHIRError? - If successful, FhirResponse record else FhirError record
bulkExport
function bulkExport(BulkExportLevel bulkExportLevel, string? groupId, BulkExportParameters? bulkExportParameters) returns FHIRResponse|FHIRError
Submits a FHIR bulk data export kickoff request
Parameters
- bulkExportLevel BulkExportLevel - Bulk export level
- groupId string? (default ()) - Group ID of the resource group to be exported. Required only if Group export level is selected
- bulkExportParameters BulkExportParameters? (default ()) - Bulk export parameters
Return Type
- FHIRResponse|FHIRError - If successful, FhirResponse record else FhirError record
bulkStatus
function bulkStatus(string? contentLocation, string? exportId) returns FHIRResponse|FHIRError
Checks the status and progress of a bulk data export request using the export task ID.
This function retrieves the export task from in-memory storage using the provided exportId
.
If the export task exists, it returns a FHIRResponse
containing the export task details as JSON.
If the export task does not exist, it returns a FHIRError
with error details.
Parameters
- contentLocation string? (default ()) - The URL to poll for the bulk export status, typically found in the response header of the kickoff request
- If provided, this URL can be used to check the status of the export
- exportId string? (default ()) - The unique identifier for the export task (used as the polling URL or status reference)
- If provided, this ID is used to retrieve the export task from in-memory storage
- If not provided, the function will attempt to use the
contentLocation
Return Type
- FHIRResponse|FHIRError - On success, returns a
FHIRResponse
record with export task details; on failure, returns aFHIRError
record
callOperation
function callOperation(ResourceType|string 'type, string operationName, RequestMode mode, string? id, map<string[]>? queryParameters, json|xml? data, MimeType? returnMimeType) returns FHIRResponse|FHIRError
Invokes a custom FHIR operation (e.g., $lookup, $everything) on a resource type.
This function allows invoking FHIR operations that are not covered by standard CRUD methods, such as $lookup
, $everything
, or any other custom operation defined by the FHIR server.
Parameters
- 'type ResourceType|string - The name of the resource type on which the operation is invoked
- operationName string - The name of the FHIR operation (e.g., "$lookup", "$everything")
- mode RequestMode (default POST) - The request mode, GET or , default is POST
- id string? (default ()) - The logical id of the resource (optional, used for instance-level operations)
- data json|xml? (default ()) - Resource data to be sent in the request body (for POST operations)
- returnMimeType MimeType? (default ()) - The MIME type of the response
Return Type
- FHIRResponse|FHIRError - If successful, FhirResponse record else FhirError record
Enums
health.clients.fhir: BulkExportLevel
Members
health.clients.fhir: BulkExportOutputType
Members
health.clients.fhir: BundleType
Types of a FHIR bundle
Members
health.clients.fhir: ExportFileServerType
Members
health.clients.fhir: MimeType
FHIR accepted MIME types
Members
health.clients.fhir: ModeType
Specifies the information that should return in the capability statement
Members
health.clients.fhir: PatchContentType
FHIR accepted PATCH content types
Members
health.clients.fhir: PreferenceType
Specifies the content that should return when performing create,update or patch
Members
health.clients.fhir: RequestMode
Members
health.clients.fhir: ResourceType
Types of resources
Members
health.clients.fhir: SummaryType
Specifies the subset of the resource to be returned
Members
Records
health.clients.fhir: BaseBulkExportParameters
Represents common parameters that can be used in bulk export kick off request
Fields
- _outputFormat string(default FHIR_ND_JSON) - Output encoding style
- _since? string - Time instant where only resources that were last updated on or after the given time will be included in the export
- _type? string[] - Array of resource types to include in the export
- _typeFilter? string[] - Array of search URL that can be used to narrow the scope of the export
health.clients.fhir: BaseSearchParameters
Represents the common search parameters across all resources
Fields
- _id? string - Logical id of this artifact
- _lastUpdated? string[] - When the resource version last changed
- _list? string - All resources in nominated list (by id, Type/id, url or one of the magic List types)
- _profile? string - Profiles this resource claims to conform to
- _query? string - A custom search profile that describes a specific defined query operation
- _source? string - Identifies where the resource comes from
- _security? string - Security Labels applied to this resource
- _tag? string - Tags applied to this resource
- _text? string - Search on the narrative text (html) of the resource
- _type? string - Used when a search is performed in a context which doesn't limit the search to indicate which types are being searched. See the FHIR search page for further discussion
- _content? string - Search on the entire content of the resource
- _filter? string - Filter search parameter which supports a more sophisticated grammar for searching
- _has? string - Provides limited support for reverse chaining - that is, selecting resources based on the properties of resources that refer to them (instead of chaining where resources can be selected based on the properties of resources that they refer to)
health.clients.fhir: BulkExportConfig
Configs of the file server where bulk export files will be stored
Fields
- fileServerType ExportFileServerType(default LOCAL) - fhir, ftp, or local
- fhir: Sync the exported files with a FHIR server
- ftp: Send the exported files to a FTP server
- local: Save the exported files in the local file system
- fileServerUrl string(default "") - Bulk export file server base url
- fileServerPort int(default 21) - Port to access the file server, default is 21
- fileServerUsername string(default "") - Username to access the server, for ftp
- fileServerPassword string(default "") - Password to access the server, for ftp
- fileServerDirectory string(default "") - Directory to save the exported files in the file server, for ftp
- pollingInterval decimal(default DEFAULT_POLLING_INTERVAL) - Bulk status polling interval in seconds, default is 2 seconds
- tempDirectory string(default DEFAULT_EXPORT_DIRECTORY) - Local directory to save the exported files, for local file server
- tempFileExpiryTime decimal(default DEFAULT_TEMP_FILE_EXPIRY) - Expiration period for temporary export files in seconds, for local file server
health.clients.fhir: BulkExportParameters
Represents parameters that can be used in bulk export kick off request, add more name value pairs if necessary
Fields
- Fields Included from *BaseBulkExportParameters
health.clients.fhir: ExportedFileUrlInfo
Represents the exported file URLs and related metadata for a bulk export operation.
Fields
- exportId string - The unique identifier for the export operation
- expiryTime? string - The expiration time for the exported files (as a string, e.g., UTC timestamp or "N/A")
- output OutputFile[] - An array of OutputFile records, each containing details about an exported file
health.clients.fhir: FHIRConnectorConfig
Represents FHIR client connector configurations
Fields
- baseURL string - FHIR server base URL
- mimeType MimeType(default FHIR_JSON) - global MIME type of the return response, can be configured at method level as well
- authConfig? (ClientAuthConfig|PKJWTAuthConfig) - Authentication configs that will be used to create the http client
- urlRewrite boolean(default false) - Whether to rewrite FHIR server URL, can be configured at method level as well
- replacementURL? string - Base url of the service to rewrite FHIR server URLs
- bulkExportConfig? BulkExportConfig - Bulk export file server configs
- httpVersion HttpVersion(default http:HTTP_2_0) - The HTTP version understood by the client
- http1Settings ClientHttp1Settings(default {}) - Configurations related to HTTP/1.x protocol
- http2Settings ClientHttp2Settings(default {}) - Configurations related to HTTP/2 protocol
- timeout decimal(default 30) - The maximum time to wait (in seconds) for a response before closing the connection
- forwarded string(default "disable") - The choice of setting
forwarded
/x-forwarded
header
- poolConfig PoolConfiguration?(default ()) - Configurations associated with request pooling
- cache CacheConfig(default {}) - HTTP caching related configurations
- compression Compression(default http:COMPRESSION_AUTO) - Specifies the way of handling compression (
accept-encoding
) header
- circuitBreaker CircuitBreakerConfig?(default ()) - Configurations associated with the behaviour of the Circuit Breaker
- retryConfig RetryConfig?(default ()) - Configurations associated with retrying
- responseLimits ResponseLimitConfigs(default {}) - Configurations associated with inbound response size limits
- proxy ProxyConfig?(default ()) - Proxy server related options
- validation boolean(default true) - Enables the inbound payload validation functionalty which provided by the constraint package. Enabled by default
- socketConfig ClientSocketConfig(default {}) - Provides settings related to client socket configuration
- secureSocket ClientSecureSocket?(default ()) - Provides settings related to SSL/TLS
health.clients.fhir: FHIRConnectorErrorDetail
Represent Connector related errors
Fields
- errorDetails? error - the full error
health.clients.fhir: FHIRResponse
Represents a success response coming from the fhir server side
Fields
- httpStatusCode int - HTTP status code from the interaction
- 'resource json|xml - Field Description
health.clients.fhir: FHIRServerErrorDetails
Represents the details of the error response that represents an unsuccessful interaction with the server
Fields
- httpStatusCode int - HTTP status code from the interaction
- 'resource json|xml - Field Description
health.clients.fhir: HistorySearchParameters
Represents parameters that can be used in a history interaction, add more name value pairs if necessary
Fields
- _count string(default "10") - The maximum number of search results on a single response
- _since? string - Only include resource versions that were created at or after the given instant in time
- _at? string - Only include resource versions that were current at some point during the specified time period
- _list? string - Only include resource versions that are referenced in the specified list
health.clients.fhir: OutputFile
Represents metadata for an exported FHIR resource file.
Fields
- 'type string -
- url string - The URL or path where the exported file can be accessed
health.clients.fhir: SearchParameters
Represents parameters that can be used in a search interaction, add more name value pairs if necessary
Fields
- Fields Included from *BaseSearchParameters
Errors
health.clients.fhir: FHIRConnectorError
Represents the error type for connector side errors
health.clients.fhir: FHIRError
Represents the errors that can be returned from the connector
health.clients.fhir: FHIRServerError
Represents the error type for an unsuccessful interaction with the server
Union types
health.clients.fhir: OnCondition
OnCondition
Represents the possible types that can be used as a condition in conditional FHIR interactions.
Used in conditional create, update, or delete operations. Can be one of:
SearchParameters
: A set of search parameters to match resources.map<string[]>
: A map of key-value pairs (with array values) representing search conditions.string
: The conditional URL directly as a string (e.g.,"identifier=12345"
).
For a conditional create, update or delete, you can:
- Provide the conditional URL directly as a string for the
onCondition
parameter. - Or, provide conditional parameters as a
SearchParameters
ormap<string[]>
to construct the conditional URL.
Import
import ballerinax/health.clients.fhir;
Metadata
Released date: 2 days ago
Version: 3.0.0
Compatibility
Platform: any
Ballerina version: 2201.12.3
GraalVM compatible: Yes
Pull count
Total: 3077
Current verison: 5
Weekly downloads
Keywords
Healthcare
FHIR
client
R4
Contributors