Helix AU Core - Local Development build (v0.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Writing Data Back to Helix

Overview

This feature enables you to securely and efficiently write FHIR resources (for example, Patient, DocumentReference, Appointment) from Helix Hub into Helix by ensuring data accuracy, traceability, and regulatory compliance.

Purpose

Consistency and synchronisation across partners

• When you update or create records, writing data back ensures Helix always reflects the latest information.
• This avoids fragmentation and duplication, helping practices manage unified, accurate records.

Supported Resource Types

Patient, DocumentReference, Appointment

1. Patient
   • Writing data back to Helix ensures patient demographics, contact information, and medical history are up-to-date between Helix Hub and Helix.
   • When patients update personal information (for example, phone number, name, date of birth, gender) or clinicians capture new clinical history during consultations via partner platforms, the data is synchronised with Helix in real-time.
2. DocumentReference
   • Writing data back to Helix is used to share clinical documents via DocumentReference and makes it accessible within Helix. It includes data such as:
     • Test results
     • Referrals
     • Intake forms
     • Pre-consultation materials
   • It ensures clinicians have access to a comprehensive view of the patient information and use it before or during consultations.
     • Most platforms allow patients to submit forms or notes prior to appointments.
     • Synchronise DocumentReference allows practitioners and clinicians to review everything available about the patients within Helix. This streamlines the workflow by removing the requirement to navigate across different platforms.
3. Appointment
   • Writing data back to Helix ensures that clinicians, administrative staff, and downstream systems have real-time access to accurate scheduling information including:
     • Booked time slots
     • Status updates (for example, confirmed, cancelled)
     • Linked patient and practitioner information
     • Maintains Real-time visibility for care coordination

The example below illustrates a step-by-step method for writing back an Appointment resource.

• Appointment created in your system:
  Patient books via portal, app, or staff interface which includes metadata, such as practitioner, time, location, and reason.

• Writeback triggered:
  Your system sends the appointment data to Helix Hub. The Helix Hub validates and publishes the FHIR Appointment resource.

• Helix consumption:
  Helix processes the resource and maps it to its internal data model. The appointment is then stored and is accessible to clinicians.

Prerequisites to Enable Writeback Capabilities

• Active subscription to Helix
• Your system is configured as an offical Helix Hub integration
• Your system is capable of generating valid FHIR resources
• Request headers (X-Request-ID) are properly managed
• Understanding of AuthoringKey requirements

AuthoringKey in Helix Data Writeback

• It ensures that each record synchronised back to Helix can be uniquely identified across multiple external platforms.
• It prevents duplication when the same resource (for example, patient form or appointment data) is transmitted through multiple systems.
• It facilitates traceability by clearly indicating the origin of the data and its path across integrated systems.
• It meets audit requirements by associating each record with its source system.

AuthoringKey Structure:

• AuthoringSystem: The ID of the source system.
  An example: Healthengine or HotDoc

• AuthoringSystemForeignKey: A unique ID of the resource in the source system.

Important: Use a GUID (Globally Unique Identifier) to ensure uniqueness across multiple instances of the source system.

An example: 550e8400-e29b-41d4-a716-446655440000

• AuthoringKey Format:

AuthoringSystem = Helix-Scheduling  
AuthoringSystemForeignKey = 22334434-6db4-4e3e-b1f0-d7804badfc1b  
AuthoringKey = Helix-Scheduling~22334434-6db4-4e3e-b1f0-d7804badfc1b

If not specified, Helix will automatically generate one, but it should be defined explicitly.

Writeback for DocumentReference

You can find more details here: Helix AU Core DocumentReference

While enabling writeback for DocumentReference:

• A new AuthoringKey must be specified when creating a DocumentReference.
• A valid Patient is required.
• Updating a DocumentReference resource is not currently supported.

In Helix, converting a DocumentReference into a document involves several steps to manage existing records and role associations appropriately.

1. Check if the document exists in Helix
   • The system first checks whether the document already exists in the Helix database.
   • If the document already exists, it is not saved again to avoid duplication.
2. Creation of content
   • If an attachment contains a URL, the contents at that URL are retrieved and converted to bytes.
   • If the attachment contains embedded data, then the contents are stored in a specific path.
3. Inbox and outbox storage
   • After creating the attachment, Helix will store the document in either the Inbox or Outbox, depending on its type and category.
   • Inbox is a system-managed repository or queue designed to receive, temporarily store, and manage incoming correspondence (such as document reference, letters, observation, and other clinical data) that is sent from external systems to Helix.
   • Outbox is a system-managed repository or queue that holds outgoing correspondence which is ready to be sent from Helix to external systems or platforms.
   • If the document attachment is a URL to its location, Helix will retrieve the document and store a copy in its database.

Writeback for Patient

You can find more details here: Helix AU Core Patient

While enabling writeback for Patient:

• It ensures Patient resources can be created and updated in Helix.
• To create a patient, the minimum required information includes: name, date of birth and address.
• To create a provisional patient, the minimum required information includes: name, date of birth, and address.

Patient resource writeback operations include various healthcare workflows to manage and maintain accurate patient data across systems. The following are common use cases for these operations:

1. Creating a new patient record
   This operation is typically performed when a new patient is added or registered in the system.
   • Context: When a new patient is admitted, the corresponding record must be created in the Helix application.
   • Example: A patient visits the medical practice for the first time and the essential information (name, date of birth, medical history) must be entered into the system.
   • Expected outcome: A unique identifier is assigned to the patient’s record, and all required data is securely stored to support clinical access.
2. Updating an existing patient
   This operation includes changing personal details, insurance information, or medical history.
   • Context: Patient data must be updated to reflect changes such as revised contact information or newly diagnosed medical conditions.
   • Example: If a patient changes their phone number or moves to a new address, the record must be updated to reflect those changes.
   • Expected outcome: The Patient’s record is successfully updated with the latest information and the changes are propagated across all relevant systems.

Patient Data Writeback examples

1. Create new patient writeback:

   You can send the request in the following format to Helix Hub (POST https://<FHIR URL>/<tenant>/Patient) and the patient will be created in Helix.

        {
          "resource": {
            "resourceType": "Patient",
            "identifier": [
              {
                "type": {
                  "text": "AuthoringKey"
                },
                "system": "system",
                "value": "AuthoringSystem~AuthoringForeignKey"
              }
            ],
            "active": true,
            "name": [
              {
                "use": "official",
                "family": "Isla",
                "given": ["Isla"],
                "prefix": [""]
              },
              {
                "use": "usual",
                "family": "Isla",
                "given": ["Mrs"],
                "prefix": [""]
              }
            ],
            "telecom": [
              {
                "system": "phone",
                "value": "<phone>",
                "rank": 1
              },
              {
                "system": "phone",
                "value": "<phone>",
                "use": "mobile",
                "rank": 1
              },
              {
                "system": "email",
                "value": "<email>"
              }
            ],
            "gender": "female",
            "birthDate": "1990-01-01",
            "address": [
              {
                "use": "home",
                "type": "both",
                "line": ["st1", "st1"],
                "city": "city",
                "state": "state",
                "postalCode": "0000",
                "country": "Australia"
              }
            ]
          }
        }
   

   You will get a response with a message: '201 created. A new resource was created successfully.'

2. Updating existing patient writeback:

   You can send the request in the following format to Helix Hub (PUT https://<FHIR URL>/<tenant>/Patient/PatientID) and the patient will be updated in Helix.

    {
      "resourceType": "Patient",
      "id": "PatientID",
      "identifier": [
        {
          "type": {
            "text": "AuthoringKey"
          },
          "system": "system",
          "value": "AuthoringSystem~AuthoringForeignKey"
        },
        {
          "type": {
            "coding": [
              {
                "system": "http://terminology.hl7.org.au/CodeSystem/v2-0203",
                "code": "MC",
                "display": "Patient's Medicare Number"
              }
            ],
            "text": "Medicare card number"
          },
          "system": "http://ns.electronichealth.net.au/id/medicare-number",
          "value": "24160966851",
          "period": {
            "end": "2024-11"
          }
        }
      ],
      "active": true,
      "name": [
        {
          "use": "official",
          "family": "Smith",
          "given": ["Adrian"],
          "prefix": ["Ms"]
        }
      ],
      "telecom": [
        {
          "system": "phone",
          "value": "<phone>",
          "rank": 1
        },
        {
          "system": "email",
          "value": "<email>"
        }
      ],
      "gender": "female",
      "birthDate": "1994-05-08",
      "address": [
        {
          "use": "home",
          "type": "both",
          "line": [
            "st1",
            "st2"
          ],
          "city": "city",
          "state": "state",
          "postalCode": "0000",
          "country": "Australia"
        }
      ]
    }
   

   You will get a response with a message: '200 OK. Request successful. The server has responded as required.'

Writeback for Appointment

While enabling writeback for Appointment:

• It ensures that the transformed Appointment resource is sent to Helix.
• If it is a new booking, Helix creates a new record.
• If it is an update, Helix modifies the existing appointment using the AuthoringKey.
• Helix acknowledges the successful writeback.

You can find more details at: FHIR Appointment, Appointments and Helix AU Core Appointment.