health.clients.fhir
Module health.clients.fhir
API
Declarations
ballerinax/health.clients.fhir Ballerina library
Overview
The connector serves as an interface for interacting with FHIR servers, allowing easy integration of FHIR data.
Usage
Import the package to a Ballerina program.
import ballerinax/health.clients.fhir;
Create the required authentication configuration. The connector can accept various client authentication configurations supported by Ballerina, such as basic authentication, token-based authentication, etc. For instance, if it is required to use the client credentials grant, the config has to be created like the following.
http:OAuth2ClientCredentialsGrantConfig ehrSystemAuthConfig = { tokenUrl: "<tokenUrl>", clientId: "<clientId>", clientSecret: "<clientSecret>", scopes: ["system/Patient.read, system/Patient.write"] };
Initialize the connector configuration record.
fhir:FHIRConnectorConfig ehrSystemConfig = { baseURL: "https://test.org/fhir/r4", mimeType: fhir:FHIR_JSON, authConfig : ehrSystemAuthConfig };
Initialize the connector.
fhir:FHIRConnector fhirConnectorObj = check new (ehrSystemConfig);
Invoke the connector operations by passing the required parameters.
fhir:FHIRResponse|fhir:FHIRError fhirResponse = fhirConnectorObj->getById("Patient", "123456");
PKJWT Support
In addition to the authentication methods supported by Ballerina, the connector also supports private key JWT authentication, which requires creating the config as following.
-
Import the health.base authentication package.
import ballerinax/health.base.auth;
-
Create the auth config.
auth:PKJWTAuthConfig ehrSystemAuthConfig = { keyFile: "<path_to_key_file>", clientId: "<clientId>", tokenEndpoint: "<tokenUrl>" };
This can be passed to the connector configuration.
Bulk Data Export Operations Support
This connector supports FHIR Bulk Data Export operations and does not require any additional configuration. However, if the generated files get stored in another file server apart from the FHIR server, add the file server configurations to the connector configuration record.
-
Update the connector config.
fhir:FHIRConnectorConfig ehrSystemConfig = { baseURL: "https://test.org/fhir/r4", mimeType: fhir:FHIR_JSON, authConfig : ehrSystemAuthConfig, bulkFileServerConfig: { fileServerBaseURL: "https://storage.test.org", fileServerAuthConfig: fileServerAuthConfig } };
Now the exported files can be accessed from the file server using the connector.
Rewrite FHIR Server URL
This connector can rewrite/replace FHIR server URL in the response payload and headers with a custom URL.
-
Update the connector config to enable this feature.
fhir:FHIRConnectorConfig ehrSystemConfig = { baseURL: "https://test.org/fhir/r4", mimeType: fhir:FHIR_JSON, authConfig : ehrSystemAuthConfig, urlRewrite: true, replacementURL: "https://my.fhir.service/r4" };
Now the FHIR server URLs will get replaced with the replacement 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
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)
- connectorConfig FHIRConnectorConfig - FHIR connector configurations
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, 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
- 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, string id, json|xml data, 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
- id string - The logical id of the resource
- data json|xml - Resource data
- 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) 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
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, MimeType? returnMimeType, PreferenceType returnPreference) returns FHIRResponse|FHIRError
Creates a new resource
Parameters
- data json|xml - Resource data
- 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, 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
- 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, MimeType? returnMimeType) returns FHIRResponse|FHIRError
Searches across all resources types
Parameters
- searchParameters SearchParameters|map<string[]> - The search parameters that are common across all resources
- 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) returns FHIRResponse|FHIRError
Checks the progress of the bulk data export. Returns the exported file locations if the export status is complete
Parameters
- contentLocation string - Bulk status polling url. Found in the response header of the kickoff request
Return Type
- FHIRResponse|FHIRError - If successful, FhirResponse record else FhirError record
bulkDataDelete
function bulkDataDelete(string contentLocation) returns FHIRResponse|FHIRError
Request to delete exported files on the server. Cancels the bulk export process if it is not completed.
Parameters
- contentLocation string - Bulk status polling url. Found in the response header of the kickoff request
Return Type
- FHIRResponse|FHIRError - If successful, FhirResponse record else FhirError record
bulkFile
function bulkFile(string fileUrl, map<string>? additionalHeaders) returns FHIRBulkFileResponse|FHIRError
Request to get the exported bulk file
Parameters
- fileUrl string - Bulk file url. Found in the response body of the bulk status request
Return Type
- FHIRBulkFileResponse|FHIRError - If successful, FhirBulkFileResponse 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: 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: 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: 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: BulkFileServerConfig
Configs of the file server where bulk export files will be stored
Fields
- Fields Included from *ClientConfiguration
- secureSocket ClientSecureSocket|()
- httpVersion HttpVersion
- http1Settings ClientHttp1Settings
- http2Settings ClientHttp2Settings
- timeout decimal
- forwarded string
- followRedirects FollowRedirects|()
- poolConfig PoolConfiguration|()
- cache CacheConfig
- compression Compression
- auth CredentialsConfig|BearerTokenConfig|JwtIssuerConfig|OAuth2ClientCredentialsGrantConfig|OAuth2PasswordGrantConfig|OAuth2RefreshTokenGrantConfig|OAuth2JwtBearerGrantConfig|()
- circuitBreaker CircuitBreakerConfig|()
- retryConfig RetryConfig|()
- cookieConfig CookieConfig|()
- responseLimits ResponseLimitConfigs
- proxy ProxyConfig|()
- validation boolean
- socketConfig ClientSocketConfig
- fileServerUrl string - Bulk export file server base url
health.clients.fhir: FHIRBulkFileResponse
Represents a bulk file response coming from the fhir server side
Fields
- httpStatusCode int - HTTP status code returned from the server
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
- bulkFileServerConfig? BulkFileServerConfig - 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: 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
Import
import ballerinax/health.clients.fhir;
Metadata
Released date: 26 days ago
Version: 2.1.0
Compatibility
Platform: any
Ballerina version: 2201.10.2
GraalVM compatible: Yes
Pull count
Total: 1469
Current verison: 71
Weekly downloads
Keywords
Healthcare
FHIR
client
R4
Contributors