> Continuous Process Improvement > Patient Journey > athenahealth > Data Template

Your Patient Journey Data Template

athenahealth

Patient Journey Attributes (20) Patient Journey Activities (15) Extraction Guides (2)

Your Patient Journey Data Template

This template provides a comprehensive guide to collecting the necessary data for analyzing your patient journey. It outlines the essential attributes and activities you need to track, along with clear guidance on how to extract this information from athenahealth. Utilize this resource to ensure your data is ready for effective process mining.

Recommended attributes to collect
Key activities to track
athenahealth extraction guidance

New to event logs? Learn how to create a process mining event log.

Download Template

Patient Journey Attributes

These are the recommended data fields to include in your event log, essential for comprehensive analysis and understanding of your patient journeys.

5 Required 10 Recommended 5 Optional

	Name	Description
	Activity Name ActivityName	The name of the event or task performed in the patient journey.
Description Indicates the specific step occurring in the process, such as 'Patient Checked In', 'Diagnostic Test Ordered', or 'Medication Administered'. This text string defines the nodes in the process map. Used to visualize the process flow and identify the sequence of operations. Standardization of these names is critical for an unclustered and readable process map. Why it matters Defines the steps of the process map and is mandatory for any process mining. Where to get Derived from audit logs, appointment status changes, or claim line item descriptions. Examples Appointment ScheduledPatient Checked InDiagnostic Test OrderedPatient Discharged
	Event Timestamp EventTimestamp	The specific date and time when the activity occurred.
Description Records the exact moment an activity took place. This is used to sequence events chronologically and calculate durations between steps. Crucial for time-based analysis, including cycle times, waiting times, and throughput analysis. High precision is preferred to resolve the order of events happening on the same day. Why it matters Required to order events and calculate all time-based KPIs. Where to get Timestamp fields associated with status changes or creation dates in athenahealth tables. Examples 2023-10-12T08:30:00Z2023-10-12T09:15:22Z2023-10-15T14:20:00Z
	Last Data Update LastDataUpdate	The timestamp when the data was last extracted or refreshed.
Description Indicates the freshness of the data used in the analysis. This helps users understand if they are looking at real-time data or a historical snapshot. Used to manage data pipelines and ensure that dashboards reflect the most current state of the process. Why it matters Critical for data governance and user trust in the dashboard's currency. Where to get System time at the moment of ETL execution. Examples 2023-11-01T12:00:00Z2023-11-02T06:00:00Z
	Patient Episode PatientEpisodeId	Unique identifier for the specific patient episode or journey.
Description This attribute serves as the central Case Identifier, grouping all activities related to a specific period of care or condition for a patient. It connects disparate events such as appointments, diagnostic orders, and discharge procedures into a single cohesive journey. In analysis, this ID is the primary key for process mining, allowing the reconstruction of the end-to-end flow. It ensures that multiple visits by the same patient for different conditions are treated as distinct process instances. Why it matters Essential for defining the scope of a single process instance within the analysis. Where to get Derived from grouping Encounter IDs or linked to a specific Episode of Care ID in athenahealth. Examples EP-2023-88491EP-2023-99102ENC-55412-GRP
	Source System SourceSystem	The name of the system where the data originated.
Description Identifies the IT system responsible for generating the record, in this case, 'athenahealth'. This is particularly useful in multi-system environments where data might be blended. Allows analysts to filter the view by data source and troubleshoot data quality issues specific to one system. Why it matters Provides data lineage and context in multi-system process mining setups. Where to get Hardcoded literal or system configuration ID. Examples athenahealthAthenaOneAthenaPractice
	Department Name DepartmentName	The hospital or clinic department where the activity occurred.
Description Segments the process data by functional unit, such as Emergency, Cardiology, or Radiology. This is essential for the 'Departmental Throughput & Handoffs' dashboard. Analysis using this attribute highlights bottlenecks in specific areas and helps optimize cross-departmental patient flow. Why it matters Crucial for identifying organizational bottlenecks and handoff inefficiencies. Where to get athenahealth 'departmentid' resolved to department name. Examples Emergency DeptInternal MedicineRadiology
	Discharge Disposition DischargeDisposition	The destination or status of the patient upon discharge.
Description Indicates where the patient went after the episode, such as 'Home', 'Skilled Nursing Facility', or 'Hospice'. This is vital for 'Discharge Planning & Readmission Trends'. It provides context on the complexity of the discharge planning required and helps assess the effectiveness of care transitions. Why it matters Critical context for discharge planning and readmission risk. Where to get athenahealth encounter fields or hospital discharge records. Examples HomeSkilled Nursing FacilityTransferred to Short Term HospitalExpired
	Encounter Type EncounterType	The classification of the visit (e.g., Office Visit, Telehealth, Emergency).
Description Defines the modality or setting of the care provided. This acts as the 'Case Type' in generic data models. Different encounter types have different expected flows and billing requirements. Filtering by this attribute is essential to avoid comparing apples to oranges in cycle time analysis. Why it matters Distinguishes between different process variants like Telehealth vs In-person. Where to get athenahealth 'encountertype' field. Examples Office VisitTelehealthEmergencySurgery
	Event End Time EventEndTime	The time when the specific activity was completed.
Description Captures the completion time of an activity, enabling the calculation of the active duration (processing time) of the step itself, distinct from the waiting time before it. Used to analyze resource efficiency and identify tasks that take longer than expected to execute manually. Why it matters Allows calculation of active processing time versus passive waiting time. Where to get Checkout time, result verified time, or specific completion timestamps in athenahealth. Examples 2023-10-12T09:00:00Z2023-10-12T10:45:00Z
	Is Readmission IsReadmission	Flag indicating if this episode represents an unscheduled return.
Description A boolean indicator identifying if the patient returned to the hospital within a set period (e.g., 30 days) of a previous discharge. This directly supports the 'Percentage of Unscheduled Readmissions' KPI. By filtering on this attribute, analysts can drill down into the root causes of readmissions and identify patterns in the initial treatment pathways. Why it matters Directly supports the Readmission Rate KPI. Where to get Calculated during ETL by comparing admission date to previous discharge date. Examples truefalse
	Patient Age Group PatientAgeGroup	Categorical grouping of the patient's age (e.g., 18-25, 65+).
Description Segments patients into demographic cohorts. This is directly required for the 'Age Group & Diagnosis Journey Comparison' dashboard. It helps identify if process inefficiencies or outcomes disproportionately affect specific age demographics, such as the elderly or pediatric patients. Why it matters Standard demographic segment for healthcare process analysis. Where to get Derived from Patient DOB and StartTime. Examples 18-2930-4965+
	Patient ID PatientId	A unique identifier for the patient (anonymized/hashed).
Description Uniquely identifies the customer (patient) undergoing the journey. While similar to the case identifier, one patient may have multiple episodes over time. Used to link repeat visits and analyze readmission rates. It is critical for the 'Percentage of Unscheduled Readmissions' KPI. Why it matters Necessary for tracking readmissions and patient history across episodes. Where to get athenahealth 'patientid' field. Examples PAT-100234PAT-559201PAT-992210
	Primary Diagnosis Code PrimaryDiagnosisCode	The primary ICD-10 code associated with the episode.
Description Classifies the clinical reason for the patient journey. This provides the context needed for 'Age Group & Diagnosis Journey Comparison'. Analysts use this to segment journeys by condition (e.g., Pneumonia vs. Fracture) because different conditions have vastly different expected pathways and cycle times. Why it matters Enables comparison of 'like' cases; cycle times vary wildly by diagnosis. Where to get Encounter or Claim diagnosis fields (ICD-10). Examples J18.9I10E11.9
	Processing Time ProcessingTime	The duration spent actively working on the activity.
Description Represents the time difference between the start and completion of a specific task (e.g., time taken to perform a scan). This maps to 'ProcessingTime' in the generic model. Used to calculate resource utilization and identify efficiency gaps in manual tasks vs. automated ones. Why it matters Differentiates active work from waiting time in the total cycle. Where to get Calculated: EventEndTime - EventTimestamp. Examples 15m1h 30m45s
	Provider Name ProviderName	The name of the healthcare professional performing the activity.
Description Identifies the specific doctor, nurse, or technician responsible for the event. This attribute is central to resource utilization analysis. It allows for the comparison of performance metrics, such as throughput and cycle time, across different staff members to identify training needs or workload imbalances. Why it matters Key for 'Resource Utilization Rate' and analyzing handoffs. Where to get athenahealth 'providerid' resolved to provider directory name. Examples Dr. SmithNurse JonesTech Adams
	Claim Status ClaimStatus	The status of the financial claim associated with the care.
Description Indicates where the billing claim stands, such as 'Submitted', 'Denied', or 'Paid'. This is relevant for the 'Claim Submitted' activity and financial throughput. Helps identify if clinical documentation issues are leading to backend financial delays. Why it matters Links clinical efficiency to revenue cycle performance. Where to get athenahealth 'claimstatus' field. Examples BILLEDHOLDDROP
	Diagnostic Result Status DiagnosticResultStatus	The outcome status of a diagnostic order (e.g., Positive, Normal).
Description Captures the high-level result of a test. This provides context for the 'Diagnostic Testing Lead Time' and subsequent treatment decisions. Used to analyze if abnormal results lead to faster subsequent actions compared to normal results. Why it matters Connects process flow to clinical outcomes. Where to get athenahealth lab result observation fields. Examples NormalAbnormalCritical
	Is Rework IsRework	Flag indicating if this activity is a repetition.
Description A boolean flag that is true if the activity has occurred more than once within the same case. This supports the 'Activity Frequency and Rework Loops' dashboard. It allows for immediate isolation of cases containing rework, facilitating the 'Frequency of Rework Activities' KPI calculation. Why it matters Identifies process inefficiencies and redundant steps. Where to get Calculated during ETL based on activity occurrences per CaseId. Examples truefalse
	Order Type OrderType	Category of the order (e.g., Lab, Imaging, Prescription).
Description Classifies clinical orders placed during the episode. This is crucial for the 'Diagnostic Testing Lead Time' dashboard. It allows analysts to measure lead times specifically for Labs versus Imaging, which often have different service level agreements and bottlenecks. Why it matters Segments the diagnostic process for specific lead time analysis. Where to get athenahealth 'ordertype' or 'class' in the orders API. Examples LabImagingPrescriptionProcedure
	Total Charge Amount TotalChargeAmount	The monetary amount charged for the activity or episode.
Description The financial value associated with the activity or the total claim amount. This enables cost-based process mining and financial impact analysis. Used to identify high-cost variations in treatment pathways and correlate process efficiency with financial outcomes. Why it matters Adds financial dimension to the process analysis. Where to get athenahealth 'amount' or 'totalcharge' in claim/charge tables. Examples 150.002500.5045.00

Required Recommended Optional

Patient Journey Activities

These are the crucial process steps and milestones to capture in your event log for accurate discovery and optimization of the patient experience.

7 Recommended 8 Optional

	Activity	Description
	Diagnosis Confirmed	A clinician officially assigns or confirms a diagnosis for the patient's condition for the current encounter. This can be inferred by the creation or 'last updated' timestamp of the primary diagnosis code, like ICD-10, associated with the patient encounter.
Why it matters This is a pivotal milestone that dictates the subsequent treatment pathway. Analyzing variations in activities after this point helps in understanding and standardizing care protocols. Where to get Inferred from the patient's problem list or the encounter's diagnosis data. A change or finalization of the diagnosis code and its associated timestamp signals this event. Capture Detect the timestamp when the primary diagnosis for the encounter is added or updated. Event type inferred
	Discharge Order Written	A physician or authorized provider writes an official order to discharge the patient from care. This is an explicit, timestamped event created within the CPOE module of the EHR.
Why it matters This activity initiates the discharge process. The time between this order and the actual discharge is a key performance indicator for 'Discharge Planning Lead Time'. Where to get Located in the orders table. The event is identified by a specific 'Discharge' order type and its creation timestamp. Capture A new record with an order type of 'Discharge' is created in the orders table. Event type explicit
	Initial Assessment Completed	Marks the completion of the first clinical evaluation, such as triage or nursing assessment, where vitals and primary complaints are recorded. This event is often inferred from the timestamp of the first signed clinical note or a completed assessment form for the encounter.
Why it matters This milestone indicates the start of clinical care. The duration from check-in to this activity is a key measure of initial patient waiting time and resource responsiveness. Where to get Inferred from the creation or signing timestamp of specific clinical documents or flowsheets in athenaClinicals. Requires identifying the relevant document types for triage or intake. Capture Identify the first timestamp on a clinical note, vitals flowsheet, or a specific intake form for the encounter. Event type inferred
	Patient Checked In	This activity signifies the patient's arrival and formal check-in for their scheduled appointment or visit. This is typically captured as an explicit status change on the appointment record within athenaClinicals or athenaCommunicator.
Why it matters This is the definitive start of the patient's on-site journey. It serves as a crucial starting point for measuring wait times and the overall cycle time of a clinical encounter. Where to get Recorded as a status update in the appointment or encounter tables. Look for a 'Checked-In' status and its corresponding timestamp. Capture A status change on the appointment or encounter object is logged with a timestamp. Event type explicit
	Patient Discharged	The patient has officially been discharged, and the in-facility portion of their journey is complete. This is the final ADT event for an inpatient encounter, captured with a precise timestamp.
Why it matters This event marks the end of the patient's main journey. It is the end-point for measuring the overall 'Patient Journey Cycle Time' and is essential for readmission analysis. Where to get This is an explicit event in the ADT system or patient encounter table, marking the final status of the encounter as 'Discharged' along with a timestamp. Capture The patient encounter status is updated to 'Discharged' and an ADT event is logged. Event type explicit
	Procedure Performed	A clinical procedure, such as surgery or a specialized therapy, is performed on the patient. This is an explicit event captured in clinical documentation, often with specific start and end times recorded in a procedure note.
Why it matters Procedures are significant milestones in a patient's treatment. Analyzing the activities before and after a procedure helps optimize pre-operative and post-operative workflows. Where to get Found within procedure notes or specific clinical flowsheets in athenaClinicals. The event timestamp is derived from the documented start or end time of the procedure. Capture A procedure note or log is created containing a timestamp for when the procedure occurred. Event type explicit
	Test Results Received	The results from a diagnostic test are finalized and made available in the patient's chart. This is usually captured when the lab or imaging system sends the results back to athenahealth, creating a timestamped entry.
Why it matters The receipt of results is a critical trigger for subsequent clinical decisions, such as diagnosis and treatment planning. This event is the endpoint for measuring diagnostic turnaround times. Where to get Located in the results or diagnostics table, linked to the original order. The event is marked by the timestamp when the result was filed or received into the patient's chart. Capture A new result record is created with a timestamp, often via an interface from a LIS or RIS. Event type explicit
	Appointment Scheduled	Represents the booking of an appointment for a patient. This event is captured explicitly when a user creates and confirms a new appointment entry in athenahealth's scheduling module, athenaCommunicator.
Why it matters This activity marks the initial engagement point for many patient journeys. Analyzing the time from scheduling to check-in helps understand patient access and pre-visit efficiency. Where to get This is an explicit event logged in the appointment or scheduling tables. It is typically associated with a creation timestamp and patient ID. Capture Event is recorded upon creation of an appointment record in the scheduling module. Event type explicit
	Claim Submitted	A claim for the services rendered during the patient encounter is generated and submitted to the payer. This is an explicit event within the athenaCollector revenue cycle management module.
Why it matters While an administrative step, this activity is crucial for analyzing the revenue cycle process that runs parallel to the clinical journey. It helps identify delays between clinical care and billing. Where to get Found in the claims or billing tables. The event is marked by a claim creation or submission timestamp. Capture A claim record is created and its status is updated to 'Submitted' with a timestamp. Event type explicit
	Diagnostic Test Ordered	A provider places an order for a diagnostic test like a lab test, imaging scan, or other procedure. This is an explicit, timestamped event created through the CPOE (Computerized Provider Order Entry) functionality in athenaClinicals.
Why it matters This is a critical decision point that initiates a diagnostic sub-process. Tracking this activity is essential for analyzing the 'Diagnostic Test Lead Time' KPI from order to result. Where to get Found in the orders table. Each order will have a patient identifier, order name, order status, and a creation timestamp. Capture A new record is created in the system's orders table with a timestamp. Event type explicit
	Follow-Up Appointment Scheduled	A follow-up appointment is scheduled for the patient after their main treatment or discharge. This event is captured explicitly when a new appointment is created in the athenaCommunicator scheduling module.
Why it matters This activity is key to understanding post-discharge care coordination and its impact on outcomes like readmission rates. It shows the continuity of care. Where to get Recorded in the appointments table. The event is identified by a creation timestamp for an appointment that occurs after the discharge date. Capture A new appointment record is created in the scheduling system. Event type explicit
	Medication Administered	A medication is physically administered to the patient by clinical staff. This is recorded explicitly in the Medication Administration Record (MAR) module of athenaClinicals, with a precise timestamp for each dose.
Why it matters This activity represents a direct treatment intervention. Analyzing its timing helps measure the 'Time to First Treatment' and ensures adherence to medication schedules. Where to get Found in the MAR data tables. Each administration event has a patient ID, medication ID, dosage, and a timestamp of administration. Capture A timestamped record is created in the MAR each time a medication is documented as given. Event type explicit
	Patient Transferred	The patient is moved from one care unit or department to another, for example from the Emergency Department to an inpatient ward. This is captured explicitly through an Admission, Discharge, Transfer (ADT) event in the EHR.
Why it matters This activity is crucial for analyzing departmental handoffs and patient flow within a facility. It helps identify bottlenecks in the 'Patient Handoff Time' and resource allocation. Where to get Recorded in the ADT event log or patient tracking tables. Each transfer event includes the patient, from/to locations, and a timestamp. Capture An ADT message or event log entry is generated with a timestamp upon patient transfer. Event type explicit
	Specimen Collected	Represents the event where a biological specimen, such as blood or urine, is collected from the patient for a lab test. This is typically an explicit event logged in the lab module or as an update to the order status.
Why it matters This is a key milestone within the diagnostic testing process. The time between ordering, collection, and results can reveal significant bottlenecks in lab workflows. Where to get This event can be found as a status change on the lab order or as a distinct event in a lab information system interfaced with athenahealth. Look for a 'Collected' status and timestamp. Capture Logged as an update to the lab order status or in a dedicated specimen tracking module. Event type explicit
	Treatment Plan Developed	Represents the formal creation and documentation of a patient's treatment plan by a clinician. This can be captured as the creation or signing of a specific 'Plan of Care' document or a set of related treatment orders.
Why it matters This activity formalizes the intended clinical pathway. It is a key point for measuring conformance to standard protocols and analyzing variations in care. Where to get Likely found in the clinical documents or orders tables. This event corresponds to the timestamp of a signed care plan note or the submission of a coordinated set of treatment orders. Capture Event is the creation or finalization timestamp of a specific treatment plan document or order set. Event type explicit

Recommended Optional

Extraction Guides

How to get your data from athenahealth

Steps

Log in to the athenaNet portal using your secure credentials.
Navigate to the Reports module via the main menu, typically found under 'Reports' > 'Report Builder' or 'Custom Reports'.
Click 'Create New Report' and select 'Encounters' or 'Patient Visit' as the primary report category. This ensures the granular data is centered around the specific patient episode.
In the 'Columns' or 'Fields' selection area, search for and add the Patient Identifier (Patient ID) and Encounter Identifier (Encounter ID) to serve as your Case Identifier.
Add the demographic and context columns required for attributes, such as Department, Provider Name, Patient Age, and Primary Diagnosis Code.
Add the specific timestamp columns corresponding to the activities. You may need to look in different field groups (e.g., 'Scheduling' for Appointment Scheduled, 'Check-in' for Check-in Time, 'Billing' for Claim Submitted). Ensure you select 'Date and Time' formats where available, not just Date.
Apply filters to the report configuration. Set the 'Encounter Date' range to your desired analysis window (e.g., Last 6 Months) and filter out 'Cancelled' or 'No Show' appointments to focus on completed journeys.
Click 'Run Report' to preview the data. Verify that the columns contain data and are not entirely null.
Select the 'Export' option and choose 'CSV' (Comma Separated Values) as the format. Do not use Excel/XLSX formatting features as they complicate processing.
Save the file locally as 'athena_raw_export.csv'.
Because the report exports one row per encounter with multiple date columns (wide format), you must reshape it into an event log (long format). Use the Python script provided in the Query section to perform this transformation.
Run the script to generate the final 'process_mining_event_log.csv' and upload this file to ProcessMind.

Configuration

Report Category: Choose 'Encounter Activity' or 'Clinicals' as the base category to capture the majority of clinical workflow steps.
Date Range: Limit the initial extraction to 3-6 months to avoid report timeouts or row limits (typically capped around 50,000 rows in standard views).
Column Selection: Ensure explicit timestamp fields are selected. Avoid calculated fields like 'Days since check-in' in favor of absolute 'Check-in Date/Time'.
Null Handling: Configure the report to display blank cells for missing data rather than custom text like 'N/A' to facilitate easier script processing.
Department Filtering: If the organization is large, filter by specific Service Locations or Departments (e.g., 'Cardiology', 'Orthopedics') to keep the dataset focused.
Permissions: The user requires 'Report Creator' or 'Clinical Reporting' permissions within athenaNet to access the Custom Report Builder.

a Sample Query config

import pandas as pd
import numpy as np
from datetime import datetime

# Configuration: Input and Output filenames
INPUT_FILE = 'athena_raw_export.csv'
OUTPUT_FILE = 'patient_journey_event_log.csv'

# Load the raw wide-format report from athenaNet
# Assumes standard CSV export. Adjust encoding if necessary (e.g., 'utf-8-sig' or 'latin1')
df = pd.read_csv(INPUT_FILE, dtype=str)

# Define the mapping between Activity Names and the columns in your athenaNet report
# You must ensure these column names match your Report Builder export headers exactly
activity_mapping = {
    'Appointment Scheduled': 'APPT_CREATED_TIMESTAMP',
    'Patient Checked In': 'CHECKIN_TIMESTAMP',
    'Initial Assessment Completed': 'INTAKE_COMPLETED_TIMESTAMP',
    'Diagnostic Test Ordered': 'ORDER_ENTRY_TIMESTAMP',
    'Specimen Collected': 'LAB_COLLECTION_TIMESTAMP',
    'Test Results Received': 'LAB_RESULT_TIMESTAMP',
    'Diagnosis Confirmed': 'DIAGNOSIS_ENTRY_TIMESTAMP',
    'Treatment Plan Developed': 'PLAN_NOTE_TIMESTAMP',
    'Medication Administered': 'MED_ADMIN_TIMESTAMP',
    'Procedure Performed': 'PROCEDURE_END_TIMESTAMP',
    'Patient Transferred': 'TRANSFER_TIMESTAMP',
    'Discharge Order Written': 'DISCHARGE_ORDER_TIMESTAMP',
    'Patient Discharged': 'DISCHARGE_TIMESTAMP',
    'Follow-Up Appointment Scheduled': 'NEXT_APPT_CREATED_TIMESTAMP',
    'Claim Submitted': 'CLAIM_SUBMISSION_TIMESTAMP'
}

# Define attribute columns to carry over to every event row
attribute_columns = {
    'ENCOUNTER_ID': 'PatientEpisodeId',
    'PATIENT_ID': 'PatientId',
    'PROVIDER_NAME': 'ProviderName',
    'DEPARTMENT_NAME': 'DepartmentName',
    'PRIMARY_DIAGNOSIS_CODE': 'PrimaryDiagnosisCode',
    'PATIENT_AGE': 'PatientAgeGroup',
    'ENCOUNTER_TYPE': 'EncounterType',
    'DISCHARGE_DISPOSITION': 'DischargeDisposition',
    'IS_READMISSION': 'IsReadmission'
}

# Initialize list to hold event rows
event_log_data = []

# Transformation Loop
for index, row in df.iterrows():
    episode_id = row.get('ENCOUNTER_ID')
    
    # Skip rows without a valid identifier
    if pd.isna(episode_id) or str(episode_id).strip() == '':
        continue

    # Iterate through each defined activity
    for activity_name, col_name in activity_mapping.items():
        timestamp_val = row.get(col_name)
        
        # Only create an event if a valid timestamp exists
        if pd.notna(timestamp_val) and str(timestamp_val).strip() != '':
            
            # Create base event object
            event = {
                'PatientEpisodeId': episode_id,
                'ActivityName': activity_name,
                'EventTimestamp': timestamp_val,
                'SourceSystem': 'athenahealth',
                'LastDataUpdate': datetime.now().strftime('%Y-%m-%d %H:%M:%S')
            }
            
            # Add attributes
            for csv_col, target_col in attribute_columns.items():
                event[target_col] = row.get(csv_col, None)
            
            event_log_data.append(event)

# Create DataFrame from the list of events
event_log_df = pd.DataFrame(event_log_data)

# Standardize Date Format (ISO 8601 Recommended)
# Adjust the format string matches the raw CSV format (e.g., '%m/%d/%Y %H:%M')
event_log_df['EventTimestamp'] = pd.to_datetime(event_log_df['EventTimestamp'], errors='coerce')

# Remove rows where timestamp parsing failed
event_log_df = event_log_df.dropna(subset=['EventTimestamp'])

# Sort by Episode and Time
event_log_df = event_log_df.sort_values(by=['PatientEpisodeId', 'EventTimestamp'])

# Output to CSV
event_log_df.to_csv(OUTPUT_FILE, index=False)

print(f"Transformation complete. Processed {len(df)} encounters into {len(event_log_df)} events.")
print(f"File saved to: {OUTPUT_FILE}")

Steps

Register API Application: Log in to the athenahealth Developer Portal and register a new application to obtain your Client ID and Client Secret. Ensure the application has scopes for Appointments, Clinicals (Charts), Orders, and Billing (Claims).
Configure Python Environment: Install the required Python libraries (requests, pandas) in your execution environment using pip install requests pandas.
Authenticate: Implement the OAuth 2.0 Client Credentials grant flow to retrieve an access token. This token must be included in the Authorization header (Bearer token) of all subsequent API calls.
Define Scope: Set the Practice ID and the date range for the extraction. Athenahealth APIs are practice-specific, so you must iterate through practice IDs if you manage multiple.
Extract Appointments: Query the /appointments/booked endpoint or /appointments/changed endpoint to retrieve base encounters. Map the appointment ID to the PatientEpisodeId. Extract 'Appointment Scheduled' from the created date and 'Patient Checked In' from the check-in time.
Iterate Encounters for Clinical Events: For each appointment ID (encounter), query the clinical sub-endpoints. Call /chart/{encounterId}/vitals for 'Initial Assessment Completed'. Call /chart/{encounterId}/orders for 'Diagnostic Test Ordered', 'Specimen Collected' (based on status), and 'Discharge Order Written'.
Retrieve Results and Diagnoses: Query /chart/{encounterId}/analyteresults or /chart/{encounterId}/labresults for 'Test Results Received'. Query /chart/{encounterId}/diagnoses for 'Diagnosis Confirmed'.
Extract Treatments and Procedures: Query /chart/{encounterId}/plan for 'Treatment Plan Developed'. Query /chart/{encounterId}/procedures for 'Procedure Performed'. Query /chart/{encounterId}/medications/admin for 'Medication Administered'.
Identify ADT and Claims: Use the appointment status history or specific hospital endpoints (if available) to capture 'Patient Transferred' and 'Patient Discharged'. Query /claims related to the appointment to extract 'Claim Submitted'.
Link Follow-ups: Identify 'Follow-Up Appointment Scheduled' by searching for subsequent appointments created for the same patient ID within the encounter timeframe.
Transform and Flatten: Parse the nested JSON responses into a flat list of event dictionaries. Convert all timestamps to ISO 8601 format. Map the fields to ActivityName, PatientEpisodeId, and EventTimestamp.
Export Data: Load the list of dictionaries into a pandas DataFrame, perform final cleaning (handling nulls), and export to a CSV file ready for ProcessMind ingestion.

Configuration

API Credentials: Requires a valid Client ID and Secret from the athenahealth Developer Portal with production access.
Practice ID: The unique numeric identifier for the medical practice context. The script must be run per practice if extracting for a network.
Date Range: Recommended extraction window is 3 to 6 months due to the volume of granular clinical data.
Rate Limiting: The athenaOne API has strict rate limits (e.g., 5 calls per second). The script includes a sleep function, but enterprise-scale extractions should implement exponential backoff.
Scopes: Ensure the token has scopes for athena/service/Athenanet.MDP.* or specific granular scopes for appointments, charts, and financial data.
Pagination: Most endpoints return a limited number of records (default 1000). The script must handle the next or offset parameters.
Department Filtering: If analyzing specific flows (e.g., Emergency vs. Outpatient), filter by department ID during the appointment fetch phase.

a Sample Query python

import requests
import pandas as pd
import time
from datetime import datetime, timedelta
import base64

class=class="hl-string">"hl-comment"># Configuration
API_KEY = class="hl-string">'YOUR_CLIENT_ID'
API_SECRET = class="hl-string">'YOUR_CLIENT_SECRET'
PRACTICE_ID = class="hl-string">'195900'  class=class="hl-string">"hl-comment"># Replace with your Practice ID
BASE_URL = class="hl-string">'https://api.athenahealth.com/preview1'  class=class="hl-string">"hl-comment"># Use production URL for live data
START_DATE = class="hl-string">'01/01/2023'
END_DATE = class="hl-string">'01/31/2023'
OUTPUT_FILE = class="hl-string">'athena_patient_journey.csv'

def get_access_token():
    url = fclass="hl-string">'{BASE_URL}/oauth2/v1/token'
    auth_str = fclass="hl-string">'{API_KEY}:{API_SECRET}'
    b64_auth = base64.b64encode(auth_str.encode()).decode()
    headers = {
        class="hl-string">'Authorization': fclass="hl-string">'Basic {b64_auth}',
        class="hl-string">'Content-Type': class="hl-string">'application/x-www-form-urlencoded'
    }
    data = {class="hl-string">'grant_type': class="hl-string">'client_credentials', class="hl-string">'scope': class="hl-string">'athena/service/Athenanet.MDP.*'}
    response = requests.post(url, headers=headers, data=data)
    if response.status_code == 200:
        return response.json()[class="hl-string">'access_token']
    else:
        raise Exception(fclass="hl-string">'Auth failed: {response.text}')

def fetch_paginated(url, headers, params):
    results = []
    while True:
        response = requests.get(url, headers=headers, params=params)
        if response.status_code == 429:
            time.sleep(2)
            continue
        if response.status_code != 200:
            print(fclass="hl-string">'Error fetching {url}: {response.status_code}')
            break
        data = response.json()
        if class="hl-string">'totalcount' in data and data[class="hl-string">'totalcount'] == 0:
            break
        class=class="hl-string">"hl-comment"># Handle different response structures (key might be appointments, orders, etc.)
        keys = [k for k in data.keys() if k not in [class="hl-string">'totalcount', class="hl-string">'next', class="hl-string">'previous']]
        if keys:
            results.extend(data[keys[0]])
        
        if class="hl-string">'next' in data and data[class="hl-string">'next']:
             class=class="hl-string">"hl-comment"># Athena pagination often uses offset or a link
             class=class="hl-string">"hl-comment"># Adjust based on specific endpoint logic if next is not a full URL
             params[class="hl-string">'offset'] = params.get(class="hl-string">'offset', 0) + len(data[keys[0]])
        else:
            break
    return results

def extract_events():
    token = get_access_token()
    headers = {class="hl-string">'Authorization': fclass="hl-string">'Bearer {token}'}
    events = []

    class=class="hl-string">"hl-comment"># 1. Fetch Appointments (Patient Episodes)
    class=class="hl-string">"hl-comment"># Using /appointments/booked for the range
    print(class="hl-string">'Fetching appointments...')
    appt_params = {
        class="hl-string">'startdate': START_DATE,
        class="hl-string">'enddate': END_DATE,
        class="hl-string">'showclaimdetail': class="hl-string">'true',  class=class="hl-string">"hl-comment"># optimize to get claim info early
        class="hl-string">'ignorepartners': class="hl-string">'true'
    }
    appointments = fetch_paginated(fclass="hl-string">'{BASE_URL}/{PRACTICE_ID}/appointments/booked', headers, appt_params)

    for appt in appointments:
        episode_id = str(appt.get(class="hl-string">'appointmentid'))
        patient_id = appt.get(class="hl-string">'patientid')
        dept_id = appt.get(class="hl-string">'departmentid')
        provider_id = appt.get(class="hl-string">'providerid')
        
        class=class="hl-string">"hl-comment"># Base Activity: Appointment Scheduled
        if appt.get(class="hl-string">'date'): class=class="hl-string">"hl-comment"># capturing creation/scheduled date requires parsing history or booking info
            class=class="hl-string">"hl-comment"># Fallback to date if created date unavailable, but typically we want class="hl-string">'scheduleddatetime'
            sched_time = appt.get(class="hl-string">'scheduleddatetime', appt.get(class="hl-string">'date') + class="hl-string">' ' + appt.get(class="hl-string">'starttime'))
            events.append({
                class="hl-string">'PatientEpisodeId': episode_id,
                class="hl-string">'ActivityName': class="hl-string">'Appointment Scheduled',
                class="hl-string">'EventTimestamp': sched_time,
                class="hl-string">'SourceSystem': class="hl-string">'athenaOne',
                class="hl-string">'PatientId': patient_id,
                class="hl-string">'DepartmentName': dept_id
            })

        class=class="hl-string">"hl-comment"># Activity: Patient Checked In
        if appt.get(class="hl-string">'startcheckin'):
            events.append({
                class="hl-string">'PatientEpisodeId': episode_id,
                class="hl-string">'ActivityName': class="hl-string">'Patient Checked In',
                class="hl-string">'EventTimestamp': appt.get(class="hl-string">'date') + class="hl-string">' ' + appt.get(class="hl-string">'startcheckin'), class=class="hl-string">"hl-comment"># combining date and time
                class="hl-string">'SourceSystem': class="hl-string">'athenaOne',
                class="hl-string">'PatientId': patient_id
            })
            
        class=class="hl-string">"hl-comment"># Activity: Patient Discharged (Ambulatory Checkout)
        if appt.get(class="hl-string">'stopcheckin'):
            events.append({
                class="hl-string">'PatientEpisodeId': episode_id,
                class="hl-string">'ActivityName': class="hl-string">'Patient Discharged',
                class="hl-string">'EventTimestamp': appt.get(class="hl-string">'date') + class="hl-string">' ' + appt.get(class="hl-string">'stopcheckin'),
                class="hl-string">'SourceSystem': class="hl-string">'athenaOne',
                class="hl-string">'PatientId': patient_id,
                class="hl-string">'DischargeDisposition': class="hl-string">'Home' class=class="hl-string">"hl-comment"># Default for ambulatory
            })

        class=class="hl-string">"hl-comment"># Activity: Claim Submitted
        if class="hl-string">'claimid' in appt:
             class=class="hl-string">"hl-comment"># Ideally query /claims/{claimId} for exact submission timestamp
             class=class="hl-string">"hl-comment"># Using appointment date as proxy if detailed claim fetch skipped
             class=class="hl-string">"hl-comment"># Here we assume we fetch claim details:
             claim_res = requests.get(fclass="hl-string">'{BASE_URL}/{PRACTICE_ID}/claims/{appt["claimid"]}', headers=headers)
             if claim_res.status_code == 200:
                 claim_data = claim_res.json()
                 if claim_data.get(class="hl-string">'billedservicedate'):
                     events.append({
                        class="hl-string">'PatientEpisodeId': episode_id,
                        class="hl-string">'ActivityName': class="hl-string">'Claim Submitted',
                        class="hl-string">'EventTimestamp': claim_data.get(class="hl-string">'createddate', claim_data.get(class="hl-string">'billedservicedate')) + class="hl-string">' 12:00:00',
                        class="hl-string">'SourceSystem': class="hl-string">'athenaCollector',
                        class="hl-string">'PatientId': patient_id
                     })

        class=class="hl-string">"hl-comment"># Clinical Data Extraction (Requires Encounter Context)
        encounter_id = appt.get(class="hl-string">'encounterid')
        if encounter_id:
            class=class="hl-string">"hl-comment"># Activity: Initial Assessment (Vitals)
            vitals = fetch_paginated(fclass="hl-string">'{BASE_URL}/{PRACTICE_ID}/chart/{encounter_id}/vitals', headers, {})
            if vitals:
                class=class="hl-string">"hl-comment"># Take the first vital sign entry time
                first_vital = sorted(vitals, key=lambda x: x.get(class="hl-string">'date') or class="hl-string">'')[0]
                events.append({
                    class="hl-string">'PatientEpisodeId': episode_id,
                    class="hl-string">'ActivityName': class="hl-string">'Initial Assessment Completed',
                    class="hl-string">'EventTimestamp': first_vital.get(class="hl-string">'date') + class="hl-string">' ' + (first_vital.get(class="hl-string">'time') or class="hl-string">'00:00'),
                    class="hl-string">'SourceSystem': class="hl-string">'athenaClinicals',
                    class="hl-string">'PatientId': patient_id
                })

            class=class="hl-string">"hl-comment"># Activity: Diagnoses
            diagnoses = fetch_paginated(fclass="hl-string">'{BASE_URL}/{PRACTICE_ID}/chart/{encounter_id}/diagnoses', headers, {})
            for diag in diagnoses:
                events.append({
                    class="hl-string">'PatientEpisodeId': episode_id,
                    class="hl-string">'ActivityName': class="hl-string">'Diagnosis Confirmed',
                    class="hl-string">'EventTimestamp': diag.get(class="hl-string">'lastmodifieddatetime', appt.get(class="hl-string">'date') + class="hl-string">' 12:00:00'),
                    class="hl-string">'SourceSystem': class="hl-string">'athenaClinicals',
                    class="hl-string">'PrimaryDiagnosisCode': diag.get(class="hl-string">'diagnosiscode')
                })

            class=class="hl-string">"hl-comment"># Activity: Orders (Labs, Procedures, Discharge)
            orders = fetch_paginated(fclass="hl-string">'{BASE_URL}/{PRACTICE_ID}/chart/{encounter_id}/orders', headers, {})
            for order in orders:
                order_type = order.get(class="hl-string">'documentationtype', class="hl-string">'')
                created_time = order.get(class="hl-string">'createddatetime', appt.get(class="hl-string">'date') + class="hl-string">' 12:00:00')
                
                if class="hl-string">'LAB' in order_type.upper() or class="hl-string">'IMAGING' in order_type.upper():
                    events.append({
                        class="hl-string">'PatientEpisodeId': episode_id,
                        class="hl-string">'ActivityName': class="hl-string">'Diagnostic Test Ordered',
                        class="hl-string">'EventTimestamp': created_time,
                        class="hl-string">'SourceSystem': class="hl-string">'athenaClinicals'
                    })
                    class=class="hl-string">"hl-comment"># Activity: Specimen Collected (Inferred from status or specific fields if available)
                    if order.get(class="hl-string">'status') in [class="hl-string">'COMPLETED', class="hl-string">'REVIEW']:
                         events.append({
                            class="hl-string">'PatientEpisodeId': episode_id,
                            class="hl-string">'ActivityName': class="hl-string">'Specimen Collected',
                            class="hl-string">'EventTimestamp': order.get(class="hl-string">'lastmodifieddatetime', created_time), class=class="hl-string">"hl-comment"># Approximation
                            class="hl-string">'SourceSystem': class="hl-string">'athenaClinicals'
                        })
                
                if class="hl-string">'SURGERY' in order_type.upper() or class="hl-string">'PROCEDURE' in order_type.upper():
                     events.append({
                        class="hl-string">'PatientEpisodeId': episode_id,
                        class="hl-string">'ActivityName': class="hl-string">'Procedure Performed',
                        class="hl-string">'EventTimestamp': order.get(class="hl-string">'performdate', created_time),
                        class="hl-string">'SourceSystem': class="hl-string">'athenaClinicals'
                    })

                if class="hl-string">'DISCHARGE' in order_type.upper():
                    events.append({
                        class="hl-string">'PatientEpisodeId': episode_id,
                        class="hl-string">'ActivityName': class="hl-string">'Discharge Order Written',
                        class="hl-string">'EventTimestamp': created_time,
                        class="hl-string">'SourceSystem': class="hl-string">'athenaClinicals'
                    })

            class=class="hl-string">"hl-comment"># Activity: Test Results Received
            results = fetch_paginated(fclass="hl-string">'{BASE_URL}/{PRACTICE_ID}/chart/{encounter_id}/analyteresults', headers, {})
            for res in results:
                events.append({
                    class="hl-string">'PatientEpisodeId': episode_id,
                    class="hl-string">'ActivityName': class="hl-string">'Test Results Received',
                    class="hl-string">'EventTimestamp': res.get(class="hl-string">'analytedatetime', appt.get(class="hl-string">'date') + class="hl-string">' 12:00:00'),
                    class="hl-string">'SourceSystem': class="hl-string">'athenaClinicals'
                })

            class=class="hl-string">"hl-comment"># Activity: Treatment Plan
            class=class="hl-string">"hl-comment"># Check for Care Plan document or assessment note
            notes = fetch_paginated(fclass="hl-string">'{BASE_URL}/{PRACTICE_ID}/chart/{encounter_id}/progressnotes', headers, {})
            if notes:
                 events.append({
                    class="hl-string">'PatientEpisodeId': episode_id,
                    class="hl-string">'ActivityName': class="hl-string">'Treatment Plan Developed',
                    class="hl-string">'EventTimestamp': notes[0].get(class="hl-string">'lastmodifieddatetime', appt.get(class="hl-string">'date') + class="hl-string">' 12:00:00'),
                    class="hl-string">'SourceSystem': class="hl-string">'athenaClinicals'
                })

            class=class="hl-string">"hl-comment"># Activity: Medication Administered
            class=class="hl-string">"hl-comment"># Look for administration records
            meds = fetch_paginated(fclass="hl-string">'{BASE_URL}/{PRACTICE_ID}/chart/{encounter_id}/medications', headers, {})
            for med in meds:
                 if med.get(class="hl-string">'events'): class=class="hl-string">"hl-comment"># Check if administration events exist
                     for event in med[class="hl-string">'events']:
                         if event.get(class="hl-string">'type') == class="hl-string">'ADMINISTERED':
                             events.append({
                                class="hl-string">'PatientEpisodeId': episode_id,
                                class="hl-string">'ActivityName': class="hl-string">'Medication Administered',
                                class="hl-string">'EventTimestamp': event.get(class="hl-string">'eventdate'),
                                class="hl-string">'SourceSystem': class="hl-string">'athenaClinicals'
                             })

            class=class="hl-string">"hl-comment"># Activity: Patient Transferred (Inferred from Hospital Stay/ADT data if available)
            class=class="hl-string">"hl-comment"># Mocking logic: If department ID changes in encounter history (requires fetching history)
            class=class="hl-string">"hl-comment"># For standard API, we check if class="hl-string">'admissionstatus' indicates transfer
            pass class=class="hl-string">"hl-comment"># Complexity high for standard extraction without Hospital scope

            class=class="hl-string">"hl-comment"># Activity: Follow-Up Appointment Scheduled
            class=class="hl-string">"hl-comment"># We check if this patient has a FUTURE appointment created around this time
            class=class="hl-string">"hl-comment"># This requires a separate query or processing the full appointment list post-loop
            class=class="hl-string">"hl-comment"># Simplified: Logic placeholder
            pass 

    class=class="hl-string">"hl-comment"># Post-processing for Follow-Ups (simplified)
    class=class="hl-string">"hl-comment"># Sort all appts by patient and date, check next appt creation date
    
    class=class="hl-string">"hl-comment"># Convert to DataFrame
    df = pd.DataFrame(events)
    df[class="hl-string">'LastDataUpdate'] = datetime.now().isoformat()
    
    class=class="hl-string">"hl-comment"># Final Validation and Export
    if not df.empty:
        df[class="hl-string">'EventTimestamp'] = pd.to_datetime(df[class="hl-string">'EventTimestamp'])
        df.sort_values(by=[class="hl-string">'PatientEpisodeId', class="hl-string">'EventTimestamp'], inplace=True)
        df.to_csv(OUTPUT_FILE, index=False)
        print(fclass="hl-string">'Successfully exported {len(df)} rows to {OUTPUT_FILE}')
    else:
        print(class="hl-string">'No events extracted.')

if __name__ == class="hl-string">'__main__':
    extract_events()

Your Patient Journey Data Template

Your Patient Journey Data Template

Patient Journey Attributes

Patient Journey Activities

Extraction Guides

athenaNet Report Builder Custom CSV Export

Steps

Configuration

a Sample Query config

athenaOne API Event Extraction with Python

Steps

Configuration

a Sample Query python

Ready to Get Started?

Optimize Your Patient Journey Now, Eliminate Bottlenecks

Your Patient Journey Data Template

Your Patient Journey Data Template

Patient Journey Attributes

Patient Journey Activities

Extraction Guides

athenaNet Report Builder Custom CSV Export

Steps

Configuration

a Sample Query config

athenaOne API Event Extraction with Python

Steps

Configuration

a Sample Query python

We value your privacy

Ready to Get Started?

Optimize Your Patient Journey Now, Eliminate Bottlenecks