Helix AU Core
0.1.0 - ci-build

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

Writing Data Back to Helix (July 2025)

Overview

Writing Data Back to Helix enables partners to securely and efficiently write FHIR resources (like Patient, DocumentReference, Appointments) from SmileCDR Hub into Helix by ensuring data accuracy, traceability, and regulatory compliance.

Purpose

Consistency & Synchronization Across Partners

  • When partners 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 kept up to date between Hub and Helix.
    • If patients update personal info (e.g. new phone number, name, DOB, gender etc) or if clinicians gather new history during consultations via partner platforms, syncing data into Helix happens immediately.
  2. DocumentReference
    • Writing Data Back to Helix is used to share clinical documents via DocumentReference and makes it accessible from 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.
      • Streamlining Pre-Consult Workflows:
        • Many partner platforms allow patients to submit forms or notes prior to appointments.
        • Syncing these via DocumentReference allows practitioners and clinicians to review everything about the patient which is available within Helix. Thus avoiding the need to jump between systems.
  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 (e.g. confirmed, cancelled)
      • Linked patient and practitioner info
      • Maintains real-time visibility for care coordination

The following example for an Appointment resource demonstrates step-by-step approach for a writeback.

  • Appointment Created in Partner system
    Patient books via portal, app, or staff interface.
    Includes metadata like practitioner, time, location, and reason.

  • Writeback Triggered
    Partner system sends the appointment data to Smile CDR Hub.
    Hub validates and publishes the FHIR Appointment resource.

  • Helix Consumption
    Helix picks up the resource, maps it to its internal model.
    Appointment is stored and made available to clinicians.

Prerequisites to Enable Writeback Capabilities

  • Active subscription to Helix
  • Smile CDR configured as middleware
  • Partner system capable of generating valid FHIR resources
  • Request headers (like X-Request-ID) properly managed
  • Understanding of AuthoringKey requirements

AuthoringKey in Helix Data Writeback

  • The AuthoringKey guarantees that each record synced back to Helix is uniquely identifiable, even across multiple partner systems or external platforms.
  • Prevents duplicate entries when the same resource (e.g., patient form or appointment data) flows through multiple systems.
  • Enables easy traceability, showing the origin of the data and how it moved across integrations.
  • Supports audit requirements by linking each record to its originating system.

AuthoringKey Structure

  • AuthoringSystem:
    The ID of the originating system.
    Examples: Healthengine, HotDoc

  • AuthoringSystemForeignKey:
    A unique ID of the resource in the originating system. This is typically a GUID (Globally Unique Identifier).
    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 provided, Helix will auto-generate one. Best practice is for partners to define this explicitly.

List Of Resources

Helix AU Core DocumentReference

Description

While enabling writeback for DocumentReference:

  • A new AuthoringKey must be specified when creating a DocumentReference.
  • It must always have a valid Practitioner Role, Patient, and Consult.
  • Updating a DocumentReference resource is not currently supported.

Usage Context

In Helix, the flow for converting a DocumentReference to a document involves several steps to ensure proper handling of existing records and roles:

  1. Check if the document exists in Helix
    • The system first checks whether the document already exists in the Helix database.
    • If the document exists, it is not saved again to avoid duplication.
  2. Creation of content
    • If an attachment contains a URL, the contents of this URL are fetched and converted to bytes.
    • If the attachment contains data, then the content is stored in a specified path.
  3. Creating Outbox item
    • After creating the attachment, Helix will store the document in either the Inbox or Outbox, depending on its type and category.
    • If the document attachment is a URL to its location, Helix will retrieve the document and store a copy in its database.

Helix AU Core Patient

Description

While enabling writeback for Patient:

  • It ensures Patient resources can be created and updated to create and update patients in Helix.
  • To create a patient, the minimum required details are: name, date of birth, gender, phone number, and address.
  • To create a provisional patient, the minimum required details are: name, date of birth, and gender.

Usage Context

Patient resource writeback operations include various healthcare workflows to manage and maintain accurate patient data across systems. Below are typical contexts in which these operations are invoked:

  1. Creating a New Patient Record This operation is typically invoked when new patients are added or registered in the system.
    • Context: When a new Patient is admitted, their record must be created in the Helix application.
    • Example: A Patient visits the hospital for the first time, and their essential information—such as name, date of birth, and medical history—needs to be entered into the system.
    • Expected Outcome: The Patient's record is created with a unique identifier, and all required data is securely stored for clinical access.
  2. Updating an Existing Patient This operation includes changing personal details, insurance information, or medical history.
    • Context: Patient data needs to be modified due to changes like updated contact details or newly diagnosed medical conditions.
    • Example: If a Patient changes their phone number or moves to a new address, their 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 reflected across relevant systems.
Examples
  1. Creating a New Patient

Request:

{
  "name": "Sumanth",
  "dob": "1998-11-01",
  "gender": "Male",
  "address": "143 Park St, Spitsvilla",
  "phone": "1372-7032",
  "authoring_system": "HospitalManagementSystem",
  "authoring_system_foreign_key": "HMS64764"
}

Response:

{
  "patient_id": "12000",
  "status": "Created",
  "message": "Patient record created successfully.",
  "authoring_system": "HospitalManagementSystem",
  "authoring_system_foreign_key": "HMS64764"
}
  1. Updating an Existing Patient

Request:

{
  "patient_id": "12000",
  "phone": "1372-6309",
  "address": "154 Lake St, Spitsvilla"
}

Response:

{
  "patient_id": "12000",
  "status": "Updated",
  "message": "Patient record updated successfully."
}
  1. Creating a Provisional Patient

Request:

{
  "name": "Hashu",
  "dob": "2000-09-23",
  "gender": "Male",
  "authoring_system": "HospitalManagementSystem",
  "authoring_system_foreign_key": "HMS374783"
}

Response:

{
  "patient_id": "34000",
  "status": "Provisional",
  "message": "Provisional patient record created. Minimum requirements met.",
  "authoring_system": "HospitalManagementSystem",
  "authoring_system_foreign_key": "HMS374783"
}

Creating New Patient WriteBack:

{
  "resourceType": "Bundle",
  "entry": [
    {
      "resource": {
        "resourceType": "Patient",
        "extension": [
          {
            "url": "http://medicaldirector.com/fhir/helix-base/StructureDefinition/sms-opt-in",
            "valueBoolean": false
          },
          {
            "url": "http://hl7.org.au/fhir/StructureDefinition/indigenous-status",
            "valueCoding": {
              "system": "https://healthterminologies.gov.au/fhir/CodeSystem/australian-indigenous-status-1",
              "code": "3",
              "display": "Aboriginal And Torres Strait Islander"
            }
          },
          {
            "url": "http://hl7.org.au/fhir/StructureDefinition/closing-the-gap-registration",
            "valueBoolean": false
          },
          {
            "url": "http://medicaldirector.com/fhir/helix-base/StructureDefinition/helix-patient-status",
            "valueCoding": {
              "system": "http://medicaldirector.com/fhir/helix-base/CodeSystem/helix-patient-status",
              "code": "2",
              "display": "Existing"
            }
          }
        ],
        "identifier": [
          {
            "type": {
              "text": "MedicalDirector AuthoringKey"
            },
            "system": "http://medicaldirector.com/fhir/id/authoring-key",
            "value": "Helix-CentreMgmt~3c3a7911-2876-431f-8d28-43366b8b66f9"
          }
        ],
        "active": true,
        "name": [
          {
            "use": "official",
            "family": "Isla",
            "given": ["Isla"],
            "prefix": [""]
          },
          {
            "use": "usual",
            "family": "Isla",
            "given": ["Mrs"],
            "prefix": [""]
          }
        ],
        "telecom": [
          {
            "system": "phone",
            "value": "0748923689",
            "rank": 1
          },
          {
            "system": "phone",
            "value": "0489203758",
            "use": "mobile",
            "rank": 1
          },
          {
            "system": "email",
            "value": "pragya@health.telstra.com"
          }
        ],
        "gender": "female",
        "birthDate": "1990-01-01",
        "address": [
          {
            "use": "home",
            "type": "both",
            "line": ["st1", "st1"],
            "city": "Abba River",
            "state": "WA",
            "postalCode": "6280",
            "country": "Australia"
          }
        ],
        "contact": [
          {
            "relationship": [
              {
                "coding": [
                  {
                    "system": "http://terminology.hl7.org/CodeSystem/v2-0131",
                    "code": "C",
                    "display": "Emergency Contact"
                  }
                ],
                "text": "daughter"
              }
            ],
            "name": {
              "text": "Test"
            },
            "telecom": [
              {
                "system": "phone",
                "value": "0713729438"
              }
            ]
          }
        ]
      }
    }
  ]
}

Updating Existing Patient WriteBack:

{
  "resourceType": "Patient",
  "id": "0c02d50f-5050-4f1b-99a3-032a1c7001c8",
  "meta": {
    "versionId": "2",
    "lastUpdated": "2025-06-21T07:36:40.554+00:00",
    "source": "#d686ee6b7c23805f43c63fcb6c3ddf76"
  },
  "extension": [
    {
      "url": "http://medicaldirector.com/fhir/helix-base/StructureDefinition/sms-opt-in",
      "valueBoolean": false
    },
    {
      "url": "http://hl7.org.au/fhir/StructureDefinition/indigenous-status",
      "valueCoding": {
        "system": "https://healthterminologies.gov.au/fhir/CodeSystem/australian-indigenous-status-1",
        "code": "3",
        "display": "Aboriginal And Torres Strait Islander"
      }
    },
    {
      "url": "http://hl7.org.au/fhir/StructureDefinition/closing-the-gap-registration",
      "valueBoolean": false
    },
    {
      "url": "http://medicaldirector.com/fhir/helix-base/StructureDefinition/helix-patient-status",
      "valueCoding": {
        "system": "http://medicaldirector.com/fhir/helix-base/CodeSystem/helix-patient-status",
        "code": "2",
        "display": "Existing"
      }
    }
  ],
  "identifier": [
    {
      "type": {
        "text": "MedicalDirector AuthoringKey"
      },
      "system": "http://medicaldirector.com/fhir/id/authoring-key",
      "value": "Helix-CentreMgmt~b70f5a36-606a-471c-856c-8115a7fa3252"
    },
    {
      "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": "0792601472",
      "rank": 1
    },
    {
      "system": "email",
      "value": "email@example.com"
    }
  ],
  "gender": "female",
  "birthDate": "1994-05-08",
  "address": [
    {
      "use": "home",
      "type": "both",
      "line": [
        "Taumata-whakatangihanga-koauau-o-tamatea-turi-pukakapiki-maunga-horo-nuku-pokai-whenua-kitanatahu",
        "Porangahau, south of Waipukurau in southern Hawke's Bay,USA"
      ],
      "city": "North Island",
      "state": "NSW",
      "postalCode": "2020",
      "country": "Algeria"
    }
  ],
  "contact": [
    {
      "relationship": [
        {
          "coding": [
            {
              "system": "http://terminology.hl7.org/CodeSystem/v2-0131",
              "code": "C",
              "display": "Emergency Contact"
            }
          ],
          "text": "Friend"
        }
      ],
      "name": {
        "text": "Linda"
      },
      "telecom": [
        {
          "system": "phone",
          "value": "0370101248"
        }
      ]
    },
    {
      "relationship": [
        {
          "coding": [
            {
              "system": "http://terminology.hl7.org/CodeSystem/v2-0131",
              "code": "N",
              "display": "Next-of-Kin"
            }
          ],
          "text": "Friend"
        }
      ],
      "name": {
        "text": "Linda"
      },
      "telecom": [
        {
          "system": "phone",
          "value": "0370101248"
        }
      ]
    }
  ]
}

Helix AU Core Appointment

More information on Appointment can be found in FHIR Appointment page.
Reference Link: Appointments

Description

While enabling writeback for Appointment:

  • It ensures the transformed Appointment resource is pushed to Helix.
  • If it’s a new booking, Helix creates a new record.
  • If it’s an update, Helix modifies the existing appointment using the AuthoringKey.
  • Helix confirms the writeback was successful.

Creating a New Appointment

Context:
An appointment needs to be scheduled for a patient, such as for a consultation, procedure, or follow-up.

Expected Outcome:
A patient calls to book a new appointment through a portal with the available slots.

Appointment Example:
A new Appointment resource is created and associated with a valid Slot, Patient, and Practitioner.

  • Initial FHIR values: 
    Appointment.status = proposed
Appointment.participant.status = needs-action
  • Helix Writeback Behavior:
    • If successfully created: 
      Appointment.status = pending
Appointment.participant.status = accepted (for PPRF, LOC)
Helix database.AppointmentStatus = booked
    • If creation fails: 
      Appointment.status = cancelled
Appointment.participant.status = declined (for PPRF, LOC)
Helix database.AppointmentStatus = deleted
  • A FHIR Subscription notification will be triggered to inform downstream providers.

Updating an Appointment

Context:
Changes are made to an existing appointment, such as rescheduling or updating the reason for visit.

Example:
A provider is unavailable at the originally scheduled time, and the appointment needs to be moved to a new slot.

Expected Outcome:

  • Original appointment is cancelled.
  • A new appointment is created with the updated details.
  • Direct updates to appointment times or slots are not supported. Cancel and rebook with same details instead.

Cancelling an Appointment

Context:
The patient cancels, or the provider becomes unavailable.

Example:
A cancellation request is received, and the appointment needs to be marked as cancelled.

Expected Outcome:
The appointment's status is updated to cancelled, and participant's status is updated to declined. Any linked systems are notified.

Appointment.status = cancelled
Appointment.participant.status = declined
  • Update the associated Slot as available.

Updating Appointment Status

Context:
Appointment status needs to reflect real-world outcomes like check-in or no-show.

Examples:

  • Patient checks in: booked → arrived
  • Patient doesn’t show up: booked → noshow
  • Visit is complete: arrived → fulfilled
  • Invalid transitions (e.g., fulfilled → booked) must be rejected.

Expected Outcome:
The updated status reflects the current state of the appointment and may trigger other workflows (e.g., billing or documentation).