Documentation of JSON Files in the EMR and Patient Information System

This documentation provides an overview of the JSON file structures gotten from a GoodX patient download. Going into the patient file there is a export patient file button that results in a .zip file. This zip file contains a folder patient

• patient
• patient/patient.json
• patient/debtor.json
• patient/workflow_events.json
• patient/debtor_source_document.json
• patient/medical_history.json

and many PDFs that will have an ID that maps back to the uid in workflow_events.json

The PDFs are electronic and searchable, but there is structured data in the stages column of the workflow_events (you are welcome to try and figure this structure out, that is why we provide it, but we take no responsibility for what you do with it, the PDFs are how we meet the requirement)

1. patient.json

This file represents a single patient object, linked to a debtor. It focuses on demographics and basic links, separate from clinical data.

Key Fields

• uid (integer): Unique patient ID.

  • Example: 3.

• entity_uid (integer): Entity link.

• debtor_uid (integer): Linked debtor.

• id (integer): Internal ID.

• name (string): First name.

  • Example: "John".

• surname (string): Last name.

  • Example: "Doe".

• nickname (string or null): Nickname.

• initials (string): Initials.

• title (string or null): Title.

• id_type (string): ID type.

• id_no (string): ID number.

• date_of_birth (string, YYYY-MM-DD): Birth date.

  • Example: "1980-01-01".

• mobile_no etc. (string or null): Contact details.

• email (string): Email.

• file_no (string): File reference.

• address1 etc. (string or null): Address fields (similar to debtor).

• gender (string): Gender.

• dependant_no (string): Dependant number (e.g., "00" for main).

• dependant_type (string): Type (e.g., "main_member").

• acc_identifier (string): Account ID.

• mygc_id (null or string): External ID.

• diary_uid (null or integer): Diary link.

• gap_medical_aid_option_uid etc. (null or string): Gap insurance details.

• private (null or boolean): Private patient flag.

• patient_inactive_reason_uid (null or integer): Inactivation reason.

• picture and picture_hashed (null or string/boolean): Profile picture info.

• benefit_check (null or boolean): Benefit verification.

• dama_ignore_icd10s (null or boolean): Ignore certain ICD-10 codes.

• employer_uid (null or integer): Employer link.

• occupation (null or string): Job.

• patient_classification_uid (null or integer): Classification.

• note (null or string): Notes.

• patient_tag_uids (null or array): Tags.

Purpose

Core patient demographics for identification and linking in the EMR.

2. debtor.json

This file represents a single debtor (payer) object, typically the entity responsible for payment (e.g., patient themselves if private, or insurance). It includes contact, address, and billing details.

Key Fields

• uid (integer): Unique debtor ID.

  • Example: 3.

• entity_uid (integer): Linked entity (e.g., clinic).

  • Example: 1.

• id (integer): Internal ID.

• name (string): Debtor's first name.

  • Example: "John".

• surname (string): Last name.

  • Example: "Doe".

• initials (string): Initials.

  • Example: "J".

• title (string): Title (e.g., "MR").

• id_type (string): Type of ID (e.g., "other").

• id_no (string): ID number.

  • Example: "1234567890123".

• mobile_no (string): Mobile phone.

• work_no (string): Work phone.

• fixedline_no (string): Landline.

• email (string or null): Email address.

• file_no (string): File reference.

• gender (string or null): Gender (e.g., "male").

• language (string or null): Preferred language.

• address1 to address4 (string or null): Physical address lines.

• postcode (string or null): Postal code.

• postal_address1 to postal_address4 (string or null): Mailing address.

• postal_postcode (string or null): Mailing postal code.

• medical_aid_option_uid (string): Medical aid plan ID.

• medical_aid_no (string): Medical aid number.

• guarantor_surname etc. (string or null): Guarantor details if applicable.

• next_of_kin_name and next_of_kin_no (string or null): Emergency contact.

• iod_date and iod_description (null or string): Injury on duty details.

• type (string): Debtor type (e.g., "normal").

• acc_identifier (string): Account identifier.

  • Example: "DEB3".

• vat_no (string or null): VAT number.

• debtor_status_uid (string): Status (e.g., "1,0").

• medical_aid_outstanding and patient_outstanding (float): Outstanding balances.

• employer_uid etc. (null or integer): Links to employer, doctors, etc.

• updated_at (string): Last update timestamp.

• medical_aid_scheme_code (string or null): Scheme code.

• iod_claim_no (string or null): Claim number.

Purpose

Manages payer information for billing. In an EMR, this ensures accurate invoicing to patients, insurers, or employers.

3. workflow_events.json

This file contains an array of objects representing clinical or administrative workflow events for a patient. Each event captures a specific interaction, such as a consultation, script (prescription), or sick note. The structure supports versioning and auditing, with events linked to patients, doctors, and service centers. The stages array holds detailed clinical data (e.g., symptoms, diagnoses, scripts), but as per guidelines, we focus on top-level keys rather than deeply nested stage details. Emphasis is placed on the meta_data object, which stores metadata like creation dates and identifiers.

Top-Level Structure

• Array of Workflow Event Objects: Each object represents a single event (e.g., a doctor's note or prescription).

Key Fields in Each Workflow Event Object

• uid (integer): Unique identifier for the workflow event.

  • Example: 70419 (a script event for patient John Doe).

• entity_uid (integer): Identifier for the entity or organization managing the record (e.g., clinic or practice).

  • Example: 1 (main clinic entity).

• workflow_event_type_uid (integer): Type of event (e.g., 90 for a script, 88 for a general examination, 92 for a sick note).

  • Inference: Codes classify events like consultations, prescriptions, or certificates.

• case_uid (integer): Links to a patient case or episode of care.

  • Example: 4604 (ongoing case for John Doe's bronchitis treatment).

• booking_uid (integer or null): Appointment or booking identifier.

  • Example: 15601 (booking for a script issuance).

• debtor_uid (integer): Links to the payer (debtor) responsible for billing.

  • Example: 100 (private payer for John Doe).

• patient_uid (integer): Unique patient identifier.

  • Example: 2935 (John Doe).

• creditor_uid (null or integer): Potential link to a creditor (e.g., supplier), often null in patient events.

• treating_doctor_uid (integer): Identifier for the treating physician.

  • Example: 6 (Dr. Jane Smith).

• referring_doctor_uid (null or integer): Referring physician, if applicable.

• service_center_uid (integer): Location of service (e.g., clinic room).

  • Example: 3 (main consultation rooms).

• treatment_date (string, YYYY-MM-DD): Date of the treatment or event.

  • Example: "2019-12-04" (date of script for acute bronchitis).

• invoice_nr (string): Invoice number associated with the event.

  • Example: "00007267" (invoice for a script).

• description (string): Brief description of the event.

  • Example: "SCRIPT" or "GENERAL EXAMINATION".

• meta_data (object): Metadata for the event, including creation/print details and identifiers.

  • locked (boolean): Whether the record is editable (false if open).
  • print_date (string or null): Date and time the document was printed.
    • Example: "2019-12-04 15:41:23".
  • create_date (string): Timestamp when the event was created.
    • Example: "2019-12-04 14:20:40.053245".
  • debtor_dbid (integer): Database ID for the debtor.
    • Example: 2559.
  • patient_dbid (integer): Database ID for the patient.
    • Example: 1.
  • print_counter (integer): Number of times printed.
    • Example: 1.
  • service_center (string): Name of the service center.
    • Example: "ROOMS - KAMERS".
  • treatment_date (string): Mirrors the top-level treatment_date.
  • last_print_user (string): User who last printed.
    • Example: "admin".
  • treating_doctor (string): Doctor's name.
    • Example: "Dr JE KOTZÉ".
  • first_print_user (string): User who first printed.
  • service_center_id (integer): ID for service center.
  • treating_doctor_id (integer): ID for treating doctor.
  • first_print_datetime (string): Timestamp of first print.
  • Inference: This object supports auditing, printing, and linking to other system components.

• stages (array of objects): Detailed clinical stages (e.g., patient info, symptoms, scripts). Not documented in depth here, but top-level includes fields like id, data (with patient details, diagnoses, scripts), depends, finalized, description, triggerdone.

  • Inference: Stages modularize the workflow (e.g., physical exam, diagnosis).

• finalized (boolean): Whether the event is complete.

• created_at (string): Creation timestamp.

• trashed (boolean): If deleted (soft delete).

• updated_by (string): User who last updated.

• updated_at (string): Last update timestamp.

• workflow_event_class_uid (integer): Class of the workflow.

• workflow_state (string or null): State (e.g., "done").

• submitted_workflow_ticket (integer or null): Ticket for submission.

• audit_data (object): Audit info, e.g., print history.

Purpose

This file logs clinical workflows, enabling tracking of patient visits, prescriptions, and notes. It's central to EMR functionality for compliance and continuity of care.

4. debtor_source_document.json

This file contains an array of financial transaction objects for a debtor. It represents the net effect of invoices, receipts, journals, and other cash flows (e.g., turnover from services minus receipts and adjustments). Often includes linked invoices with their net financial impact (e.g., outstanding balances). Unlinked journals or receipts may appear. Focus is on billing cycles, with columns for original amounts, adjustments, and splits between medical aid and patient liability.

Top-Level Structure

• Array of Transaction Objects: Each object is a financial entry (e.g., turnover from a consultation).

Key Fields in Each Transaction Object

• uid (integer): Unique transaction ID.

• type (string): Type (e.g., "cashflow", "turnover", "journal").

  • Inference: "turnover" for billable services; "cashflow" for unlinked payments (prepayments) and "journal" for unlinked journals (opening balances).

• entity_uid (integer): Entity link.

• debtor_uid (integer): Debtor link.

• patient_uid (integer or null): Patient link.

• case_uid (integer or null): Case link.

• credit_control_status_uid (null or integer): Credit status.

• treating_doctor_uid etc. (null or integer): Doctor/service links.

• document_no (string): Document number (e.g., invoice or receipt).

  • Example: "00004863" (invoice for John Doe's consultation).

• resolved (boolean): If settled.

• icd10s (array of strings or null): ICD-10 diagnosis codes.

  • Example: ["D23.9"] (skin lesion).

• procedures (array of strings or null): Procedure codes.

  • Example: ["0191", "02010XY1"] (consultation codes).

• service_date (string, YYYY-MM-DD): Date of service.

• post_period (integer): Accounting period (e.g., YYYYMM).

• cca_last_touch etc. (null or string): Credit control dates.

• episode_series and episode_no (null or string/integer): Episode tracking.

• original_turnover (float): Original billed amount.

  • Example: 1584.11 (total for a procedure).

• medical_aid_original_turnover and patient_original_turnover (float): Splits by payer.

• turnover, medical_aid_turnover, patient_turnover (float): Adjusted billed amounts.

• outstanding, medical_aid_outstanding, patient_outstanding (float): Unpaid balances.

• receipts, medical_aid_receipts, patient_receipts (float): Payments received (negative for credits).

  • Example: -1584.11 (full payment received).

• refunds, medical_aid_refunds, patient_refunds (float): Refunds issued.

• journals, medical_aid_journals, patient_journals (float): Adjustments (e.g., write-offs).

• created_at and updated_at (string): Timestamps.

• updated_by (string): Updater.

Purpose

Tracks financial net effects (e.g., invoice minus receipts/journals). In an EMR, this supports billing, aging analysis, and reconciliation, showing how invoices resolve to zero outstanding via payments/adjustments.

5. medical_history.json

This file represents a single patient's medical history object. It aggregates various aspects of the patient's past and ongoing health information, such as family history, allergies, and vaccinations. Fields can be null if no data is recorded, but when populated, they use structured objects or arrays for detailed entries. This structure supports comprehensive patient profiling in the EMR, with sub-fields for notes, dates, and specific details.

Key Fields

• uid (string): Unique identifier, often combining patient UID and type.

  • Example: "3967,doctor" (though type is "doctor", it seems to store patient-like history; possibly a misnomer or dual-use).

• patient_uid (integer): Links to the patient.

  • Example: 3967 (John Doe).

• type (string): Type of record (e.g., "doctor" in example, but may vary; inference: could indicate perspective or category).

  • Inference: Specifies the context, potentially for different user types.

• entity_uid (integer): Entity or organization link.

  • Example: 1 (main clinic entity).

• general_health (null or object): Overview of lifestyle and health habits.

  • alcohol (object): With note (string) and value (string, e.g., "1-5" for consumption level).
  • smoking (object): With note and value (e.g., "Ex-Smoker").
  • exercise (object): With note and value (e.g., "2" for frequency level).
  • general_notes (string): Free-text notes.
    • Example: "General good health though he spent his youth being a bit careless".
  • important_message (string): Key alerts.
    • Example: "Don't ask about the family, sensitive topic".
  • recreational_drugs (object): With note and value (e.g., "Previously").
  • Inference: Captures risk factors for holistic health assessment.

• family_history (null or array of objects): Hereditary conditions.

  • Each object: note (string, e.g., relatives affected), value (boolean, true if present), description (string, condition name).
  • Example: {"note": "Mother", "value": true, "description": "Heart Disease"}.
  • Inference: Tracks genetic risks.

• chronic_items (null or array of objects): Chronic conditions and medications.

  • Each object: date (string, YYYY-MM-DD), lines (array of medication objects), diagnosis (array of diagnosis objects), description (string), auto_add_to_invoice (boolean).
  • Medication in lines: qty (integer), code (string), dose (integer), notes (array), route (string), period (string), repeat (integer), signata (string, instructions), expanded (boolean), schedule (integer), diagnosis (array), frequency (integer), fullnappi (string), qty_words (string), description (string), presentation (string), days_supplied (integer), days_supplied_override (integer), not_substitutable (boolean, optional).
  • Diagnosis: Similar to ICD-10 structure with pmb (boolean), code (string), etc.
  • Example: Chronic diabetes with metformin prescription.
  • Inference: Manages ongoing treatments for billing and monitoring.

• no_allergies (null or boolean): Flag for no known allergies.

• warning (null or object): Critical alerts.

  • urgent (boolean): Priority flag.
  • message (string): Warning text.
    • Example: "VERY ALLERGIC TO ALMOST EVERYTHING".
  • Inference: Prompts immediate attention in consultations.

• drug_classes (null or array of objects): Allergies to drug categories.

  • Each: code (string), note (string), type (string, e.g., "drug_classes"), description (string).
  • Example: {"code": "A01", "note": "Swelling", "type": "drug_classes", "description": "Aminoglycosides"}.

• chemical_ingredients (null or array of objects): Allergies to chemicals.

  • Similar structure: code (string), note, type (e.g., "chemical_ingredients"), description.
  • Example: {"code": "38900", "note": "", "type": "chemical_ingredients", "description": "SILDENAFIL CITRATE"}.

• natural_ingredients (null or array of objects): Allergies to natural substances.

  • Similar: code (integer), note, type (e.g., "natural_ingredients"), description.
  • Example: {"code": 33, "note": "Discomfort", "type": "natural_ingredients", "description": "Cheese"}.

• operation_history (null or array of objects): Surgical history.

  • Each: date (string, YYYY-MM-DDTHH:MM:SS), note (string), doctor (string), hospital (string), operation (string).
  • Example: {"date": "2020-02-05T00:00:00", "note": "Had to have the patella removed", "doctor": "DR JOHNSON", "hospital": "ZAH", "operation": "Knee operation"}.

• treatment_history (null or array of objects): Past treatments.

  • Each: place (string), dr_note (string), end_date (string), begin_date (string), description (string).
  • Example: {"place": "Wilgers", "dr_note": "He was treated and is in complete remission", "end_date": "2021-08-01T00:00:00", "begin_date": "2021-01-01T00:00:00", "description": "Cancer treatment for lymphoma"}.

• gynaecological_history (null or object): Reproductive health history (for applicable patients).

  • Inference: May include menstrual, pregnancy details if populated.

• occupational_and_demographical_history (null or object): Work and demographic factors.

  • note (string): Risks or details.
  • occupation (string).
    • Example: {"note": "Risk of heavy metals poisoning.", "occupation": "Mining engineer"}.
  • Inference: Assesses environmental exposures.

• vaccinations (null or array of objects): Immunization records.

  • Each: date (string), vaccination (string).
  • Example: {"date": "2025-08-29T00:00:00", "vaccination": "Yellow fever"}.

• travel_history (null or array of objects): Travel-related info.

  • Each: to (string, date), from (string, date), location (string), additional_information (string).
  • Example: {"to": "2025-09-15T00:00:00", "from": "2025-09-01T00:00:00", "location": "Mozambique", "additional_information": "Malaria risk, got all the vaccinations"}.

Purpose

Stores a patient's historical medical data for quick reference in consultations. In an EMR, this aids in risk assessment, allergy checks, and personalized care planning. Structured arrays/objects allow detailed, queryable history.

6. Patient Population Export

For exporting out the entire patient population, please contact GoodX Support for assistance. You can log a ticket with an email to help@goodx.us, or log one on your client portal, or give us a call.