Skip to main content

Fiyaware Documentation

Overview​

This user manual describes the functional properties of Black Tusk's FHIR Server.
Fiyaware enables fast and secure processing, validation, and management of large amounts of health-related or medical data according to HL7 FHIR Version 4.0.1. Fiyaware is a high-performance Python implementation with a swappable storage unit (currently PostgreSQL DB).
The server, through its central FHIR API, allows both semantically interoperable exchange of structured health data and their long-term, secure, and cost-effective archiving.
As a modular data management and communication platform, Fiyaware ensures the simple and secure connection and networking of external applications and services to enable evidence-based care across the entire healthcare sector.

Discovering Fiyaware Server​

A Fiyaware Server instance can be set up and ready to use within a few minutes. Fiyaware can be deployed locally or in cloud environments such as Azure; Docker and Kubernetes are supported.

Personalization and Deployment​

Once the deployment type is decided, Fiyaware Server can be customized to meet individual needs. Numerous parameters can be adjusted in the settings; see the section Configuration Variables.
Authentication via SMART on FHIR is also possible; see the section SMART on FHIR.

Further Information and Questions​

If further information, special features, or assistance with integrating Fiyaware Server into your system landscape are needed, we are available at the email address info@blacktusk.eu.

Getting Started​

General Installation​

Fiyaware Server can be deployed locally or in cloud environments such as Azure or AWS. An instance is provided as a Docker container.
For more information, see Security and Tools - SMART on FHIR.

Using Fiyaware Server with HTTP Clients​

Fiyaware Server is compatible with all common HTTP clients. Extensive compatibility tests have been conducted for Postman, Insomnia, and Bruno.

Setting up Fiyaware Server​

Deployment​

Depending on the use case, Fiyaware Server can be configured and deployed in several ways. These include local deployment or deployment via a Docker container, either locally or in the cloud.

Local Deployment​

Local deployment is particularly suitable for development and test environments, where quick deployment time is a priority.
No external infrastructure or additional software tools are required, simplifying deployment significantly.

Deployment via Docker Container​

Deployment as a Docker container is especially suitable for easy integration with minimal effort into existing CI/CD pipelines.

Settings​

Fiyaware Server settings can be customized through a variety of variables; see the chapter Configuration Variables.

Logging​

Logging can also be configured in the settings. An overview of the logged data and its description is provided in the chapter Auditing and Logging.

Features​

FHIR RESTful API​

FHIR Versions​

Currently, Fiyaware Server only supports FHIR R4. Support for FHIR R6 is planned, and other FHIR versions can be implemented upon customer request.

Supported Data Formats​

Fiyaware supports JSON and XML data formats. It is possible to send the same FHIR resource to the server in JSON format and retrieve it in XML format (and vice versa).

Supported FHIR Resources​

Fiyaware supports all FHIR resources of HL7 FHIR version 4.0.1.

Validation of Resources and Extensions​

Fiyaware supports complete validation of resources, including extensions.

UUIDs​

The server allows the use of both lowercase and uppercase UUIDs.

FHIR CapabilityStatement​

FHIR functionalities supported by Fiyaware can be retrieved via the server’s CapabilityStatement.
The CapabilityStatement provides a machine-readable description of implemented FHIR functionalities such as CRUD (Create/Read/Update/Delete), individual and system-wide search parameters and operators (including custom operators), as well as a list of all supported FHIR resources.

GET [baseUrl]/metadata

Supported Headers​

Fiyaware supports the HTTP header parameters "content-type" and "accept".

Supported MIME types for "content-type" and "accept" headers:

  • JSON (default)

    • JSON → interpreted as application/fhir+json
    • application/json → interpreted as application/fhir+json
    • text/json → application/fhir+json

  • XML

    • XML → interpreted as application/fhir+xml
    • application/xml → interpreted as application/fhir+xml
    • text/xml → application/fhir+xml
Content-type​

The content-type parameter specifies the input format in which the FHIR resource is sent to the server.

  • If the content-type parameter is not specified, the default value JSON is used.
  • If the content-type parameter is specified but unknown, a 415 Unsupported Media Type error code is returned.
  • For FHIR Binary, any content-type is possible but is not checked for correctness.
Accept Header​

The accept header defines the format of the HTTP response returned by the server.

  • If the accept header is not specified, the default value JSON is used.
  • If the accept header is specified but unknown, a 406 HTTP status code within an OperationOutcome is returned.
  • For FHIR Binary, any accept header is possible.
  • If a _format parameter is provided in the request, it overrides the accept header.
Handling Internal and External References​

Fiyaware supports two configurable headers for handling references: Prefer: handling=strict and Prefer: handling=lenient.

Lenient​
  • This is the default header.
  • Allows the use of the following references:
    • [server url]/ResourceType/valid-uuid-that-can-point-to-nothing
    • A valid external URL
Strict​
  • Allows the use of the following references:
    • [server url]/ResourceType/valid-uuid-that-points-to-an-existing-resource
    • A valid external URL
Return Preference​

The return preference defines the format in which resources are returned.

Allowed return preferences:

  • return=minimal
  • return=representation
  • return=OperationOutcome

If the return preference is not specified, the default value minimal is used.
If the return preference is invalid, the default value minimal is used.

In case of erroneous interactions, an OperationOutcome is always returned.

Create​

A FHIR resource can be created using an HTTP POST request:

POST [baseUrl]/resourceType

When performing a "create" with a FHIR resource, the request body must be filled and correspond to the specified "resourceType". The resource is validated for correctness during creation.
The server ignores the following fields in POST requests by default:

  • id
  • meta.versionId
  • meta.lastUpdated

The "id" and "versionId" fields are automatically set or updated by the server. The "lastUpdated" field is replaced with the current server time.
Except for the specified metadata, resources are never semantically modified.

Conditional Create​

Note: Conditional Create is currently still in a "Trial Use" phase of the FHIR standard. The status and functionality may change in future FHIR versions. Use at your own risk.

Fiyaware supports Conditional Create to create a resource only if it does not already exist.

Read​

A FHIR resource can be read using an HTTP GET request:

GET [baseUrl]/resourceType/id

The "read" method returns the requested FHIR resource.

Note: FHIR resources are never validated by the server when read.

Update​

A FHIR resource on the server can be updated via HTTP PUT request:

PUT [baseUrl]/resourceType/id

During a PUT update, both the "resourceType" and "id" fields must be present. The updated resource body must also be included.
The server ignores the following fields if provided:

  • meta.versionId
  • meta.lastUpdated

The "versionId" field is updated by the server. The "lastUpdated" field is replaced by the current server time.

Conditional Update​

Note: Conditional Update is currently in a "Trial Use" phase of the FHIR standard. The status and functionality may change in future FHIR versions. Use at your own risk.

Fiyaware supports Conditional Update to update a resource based on filter or search criteria (rather than id).

Update as Create​

Fiyaware supports the "update as create" functionality. The client sends a PUT request including a FHIR resource.

  • If the resource exists on the server, it is updated.
  • If the resource does not exist, it is created, and the server automatically assigns an id.
  • The client cannot set the resource id manually.

PUT [baseUrl]/resourceType/id

Delete​

A FHIR resource can be deleted using an HTTP DELETE request:

DELETE [baseUrl]/resourceType/id

The "delete" method removes the specified resource(s). Afterwards, the resource cannot be read or searched.

Note: When deleting one or more resources, the request body must be empty; otherwise, HTTP status code "400 – Bad Request" is returned.

Conditional Delete​

Note: Conditional Delete is currently in a "Trial Use" phase of the FHIR standard. The status and functionality may change in future FHIR versions. Use at your own risk.

Fiyaware supports Conditional Delete to remove a resource based on filter or search criteria.

Patch​

Fiyaware supports Patch for JSON. Unlike a regular PUT, only the content to be updated is sent to the server, not the entire resource body.

PATCH [baseUrl]/resourceType/id

For Patch, the "content-type" header must be set to "application/json+patch+json".

History​

vread​

Fiyaware supports version-specific reading of resources.
The version of a resource can be requested using an HTTP GET request:

GET [baseUrl]/resourceType/id/_history/[vid]

Resource Level​

Returns a list of all historical versions of a specific resource:

GET [baseUrl]/resourceType/[id]/_history

Resource Type Level​

Returns a list of all historical versions of a specific resource type:

GET [baseUrl]/resourceType/_history

Global Level​

Returns a list of all historical versions available in the system:

GET [baseUrl]/_history

Optional Parameters​
_since​

The historical list can be limited to a specific timeframe and only include versions created on or after a specified date:

GET [baseUrl]/resourceType/_history?_since=2015-02-07T13:28:17.239+02:00

_count​

Limits and extends the number of results per page:

GET [baseUrl]/_history?_count=3

Paging​

If more than 20 historical resources are requested, paging is applied by default, showing 20 resources per page. Navigation between pages is possible.

Configuration Variables​

Fiyaware Server can be customized according to individual needs. The following list provides an overview of the configurable parameters:

SettingConfigurable Default ValueDescription
FHIR_BASE_URLhttp://fhir-engine:8000Base server URL
LANGUAGE_CODEen-usLanguage
TIME_ZONEEurope/ViennaTime zone
ADMIN_URLadmin/Access control panel
DATA_UPLOAD_MAX_SIZE_MB10Maximum upload size
DEFAULT_SUPERUSER_USERNAMEadminOAuth2 setting
DEFAULT_SUPERUSER_PASSWORDfhir-engineOAuth2 setting
USE_AUTHFalseEnable/disable authentication
ACCESS_TOKEN_LIFETIME_MINUTES5Access token settings
REFRESH_TOKEN_LIFETIME_DAY1Access token settings
SLIDING_TOKEN_LIFETIME_MINUTES5Access token settings
SLIDING_TOKEN_REFRESH_LIFETIME_DAYS1Access token settings
CELERY_BROKER_URLredis://redis:6379Celery broker URL
CELERY_TASKS_ALWAYS_EAGERFalseFor asynchronous background tasks
USE_DBpostgresqlDatabase settings
POSTGRES_USERpostgresDatabase settings
POSTGRES_PASSWORDsecure-postgres-passwordDatabase settings
DEFAULT_FHIR_MIMETYPEapplication/fhir+jsonFHIR API settings
DEFAULT_FHIR_VERSION4.0.1FHIR standard version
DEFAULT_FHIR_PREFERminimalDefault "prefer" setting
MAX_RESOURCE_SIZE_MB1Maximum resource size
MAX_BINARY_RESOURCE_SIZE_MB5Maximum binary size
MAX_BUNDLE_RESOURCE_SIZE_MB5Maximum bundle size
MAX_BUNDLE_RESOURCE_ENTRIES100Maximum number of entries in bundles
DEFAULT_PAGE_SIZE20Default "paging size"
MAX_PAGE_SIZE100Maximum page size defined by "_count" parameter
SUPPORT_HISTORYTrueEnable/disable FHIR history
DEFAULT_HISTORY_PAGE_SIZE20Default paging size when using FHIR history
MAX_HISTORY_PAGE_SIZE100Maximum number of entries in history bundles
LOGSTASH_HOSTLocalhostHost
LOGSTASH_PORT5000Port
LOGSTASH_VERSION1Logstash for logging
LOGSTASH_LEVELInfoInformation configuration
LOGSTASH_MESSAGE_TYPElogstashMessage type

FHIR Bundle Handling​

Fiyaware Server supports FHIR bundles of types "document", "message", "transaction", "transaction-response", "batch", "batch-response", "searchset", and "collection".

FHIR Transaction Bundle​

With support for FHIR transactions, Fiyaware allows multiple actions (CRUD + Search) within a bundle of type "transaction" or a single HTTP request. A successful transaction results in a bundle of type "transaction-response" (with paging). Transactions within transactions are not allowed.

POST [baseUrl]/

Note: Fiyaware ensures transactional safety. If one action within the transaction fails, the entire set of actions fails as well.

FHIR Batch Bundle​

With support for bundles of type "batch", Fiyaware allows multiple actions (CRUD + Search) within a single batch bundle or HTTP request. A successful batch results in a bundle of type "batch-response" (with paging).

POST [baseUrl]/

Note: If one interaction fails, the remaining interactions in the bundle are still executed.

FHIR Document Bundle (MIO = Medical Information Object)​

Fiyaware supports processing of medical information objects. These FHIR documents are defined by standardization bodies (e.g., KBV, gematik) to provide standardized and interoperable information blocks.
Fiyaware provides both the "[baseUrl]/" and "[baseUrl]/Bundle" endpoints for processing these documents.

Resource Validation​

Fiyaware supports full validation of resources, including any extensions that may be present.

FHIR Operations​

Patient-level data export with "$everything"​

The "$everything" operation allows retrieving a subset of all patient information contained in the Patient Compartment.
The $everything operation is only possible at the individual resource level.

GET [baseUrl]/Patient/id/$everything

No additional parameters have been implemented for this operation yet.

If resources in the Patient Compartment reference other resources that are not part of the Patient Compartment according to the FHIR standard, these are excluded from the return bundle for privacy reasons.

Metadata retrieval with "$meta"​

The "$meta" operation allows retrieving a summary of profiles, tags, and security labels used.

System Level​

GET [baseUrl]/$meta

Resource Type Level​

GET [baseUrl]/[resourcetype]/$meta

Resource Level​

GET [baseUrl]/[resourcetype]/[id]/$meta

Historical Resources​

GET [baseUrl]/[resourcetype]/[id]/_history/[vid]/$

Custom Operations​

Hard Delete with "$expunge"​

The proprietary operator "$expunge", not part of the FHIR standard, allows permanent ("hard") deletion of FHIR resources. After deletion, the resources are no longer present and cannot be restored. Both active and historical data can be completely deleted.

Note: Hard deletion is irreversible. Data cannot be restored. The server does not maintain referential integrity when deleting resources. When historical entries are deleted, all older versions than the specified one are also removed to maintain "_history" traceability.

DELETE [baseUrl]/resourceType/id/$expunge

DELETE [baseUrl]/resourceType/id/_history/versionID/$expunge

Database​

For performance and optimization reasons, only a PostgreSQL database is currently supported. Other databases can be implemented on customer request.

Tools and Security​

FHIR Clients​

Fiyaware is compatible with all FHIR R4-compliant libraries and third-party clients. The following commonly used FHIR clients have undergone extensive compatibility testing with Fiyaware Server:

Access Control​

SMART on FHIR​

The standalone launch process of SMART on FHIR v2.2.0 for connecting applications and apps is being implemented. See the SMART on FHIR v2.2.0 specification.
It includes OAuth 2.0-compliant user authorization and requires implementation of the Patient Compartment.

FHIR Compartments​

Fiyaware supports creation and use of FHIR Compartments, a logical grouping of resources with a commonality—here, belonging to a specific patient. FHIR Compartments offer two main advantages:

  • Related resources can be quickly found by accessing all resources in a compartment.
  • Fine-grained access control can be implemented, restricting user access to resources within a specific compartment, preventing unauthorized access.

The definition of FHIR Compartments currently applies only to the FHIR Patient Compartment, which contains all resources assigned to a specific patient. A complete list of resources in this compartment is available in the FHIR documentation.

Access restrictions for each resource in the compartment can be defined, e.g., what a patient can access, create, save, or update.
For searching compartments, see Patient Compartment Search.

Auditing and Logging​

For traceability, debugging, and status monitoring, information can be recorded during operation. This function must be enabled in the settings. The following information is currently logged for each incoming HTTP(S) request:

  • Time of authentication
  • Time of request received
  • All authentications (successful and unsuccessful, e.g., invalid access token)
  • Actions: HTTP(S) GET, POST, PUT, DELETE, SEARCH
  • Server Endpoint
  • Content-Length & Content-Type
  • Host
  • User agent (originator of the request, e.g., browser or Python request library)
  • All server responses
  • Header information
  • Representation format
  • Duration
  • Status code
  • Error message

Additionally, the following system information is recorded:

  • Changes in system states and exceptions, e.g., database exceptions
  • When resource limits are reached (e.g., full database)
  • Startup, shutdown, and restarts

FHIR Facade​

Fiyaware can be used both as a standalone server and as a facade for existing databases, making them accessible via a FHIR interface.

Facade Setup​

The FHIR facade is provided as a Docker container for platform-independent deployment. Custom search parameters and operators can be implemented upon request. Assistance can be provided for integration and testing within customer systems.

Database Mapping​

One of the most complex parts of integrating the FHIR facade into customer systems is database mapping. It ensures that customer data is optimally mapped to FHIR resources and elements. Mapping schemes from the customer database to FHIR and vice versa are provided.

The server supports search with AND, OR, and AND/OR operators:

GET [base]/

GET [base]/resourceType

POST [base]/_search

POST [base]/resourceType/_search

Supported Search Parameters​

Fiyaware supports all resource-specific search parameters, including chaining and reverse chaining. Additionally, the following "Parameters for all resources" are supported:

  • _id
  • _lastUpdated
  • _tag
  • _profile
  • _security
  • _has
  • _type

Sorting and structuring parameters:

  • _sort: Specify the order of search results
  • _count: Defines the number of resources per page
  • _include: Include resources related to search results
  • _revinclude: Fetch a resource and all resources referencing it

Search for resources linked to a patient:

GET [baseUrl]/Compartment/id/type

Paging​

Fiyaware supports paging for search results. For a "searchset" bundle, links to first, last, next, and previous pages are provided:

  • Results on a page remain unchanged when paging
  • Default page size: 20 resources
  • Maximum "_count": 100 resources per page

Compliance and Certification​

Supported Implementation Guides​

Fiyaware Server currently supports selected implementation guides required for projects and clients. Additional guides can be implemented upon customer request.

FHIR Base IG​

Fiyaware fully supports the FHIR standard 4.0.1.

Hospital IT Systems (ISiK) - DE​

Supports ISiK basic module (version 1).

HL7 Austria - AT​

Supports HL7 Austria FHIR Core IG R4.

Certifications​

EN/ISO 13485​

Development of Fiyaware Server is conducted and supervised under EN ISO 13485-certified quality management.

ISO 9001​

Fiyaware Server development complies with ISO 9001.

GDPR​

Fiyaware is GDPR-compliant through hard delete implementation (see section).

ISiK​

Fiyaware Server is compatible with ISiK Level 1; work continues on additional levels.

KBV​

Fiyaware Server is compatible with medical information objects (MIOs) issued by KBV.

Contact Us​

For questions, suggestions, or technical support, contact us at email address info@blacktusk.eu.