How the FHIR sync works

  • Release version: Australia
  • Updated June 16, 2026
  • 2 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of How the FHIR sync works

    The FHIR sync process in ServiceNow Healthcare Operations automates importing four key FHIR resources daily into the Healthcare data model. This sync is managed by a scheduled job that ensures data consistency and updates by importing resources in a specific dependency order, handling updates idempotently, and logging outcomes for monitoring and troubleshooting.

    Show full answer Show less

    Scheduled Orchestration and Process Flow

    • A scheduled job named FHIR Sync — Daily runs by default at 03:00 instance time, triggering an orchestration subflow called Import FHIR Resources.
    • The orchestration generates a unique correlation ID for each sync run and sequentially imports the four FHIR resource types through dedicated subflows.
    • Runs can also be started manually using the job’s Execute Now action.

    Dependency Order and Resource Relationships

    The four resource types are imported respecting their interdependencies to maintain referential integrity:

    • Organizations: Imported first, as Locations and PractitionerRoles reference them.
    • Locations: Reference their managing Organizations.
    • Practitioners: Represent users referenced by PractitionerRoles.
    • PractitionerRoles: Imported last, referencing both Organizations and Practitioners.

    If an earlier resource import fails, the sync run halts to prevent data inconsistencies.

    Idempotent Upsert and Matching Logic

    Each FHIR resource is matched to existing Healthcare records using the FHIR logical ID stored as externalid on primary tables (Organization, Location, Practitioner). Related records without this column use natural keys (e.g., user email) for matching. This ensures that re-importing the same resource updates existing records rather than creating duplicates, making repeated syncs safe and reliable.

    Initial Load and Delta Synchronization

    • The first sync performs a full load of all four resource types.
    • Subsequent syncs perform delta updates by requesting only resources changed since the last successful run, based on timestamps recorded in the FHIR Sync Log.

    Logging and Error Handling

    • Each sync run logs one entry per resource type, linked by the correlation ID, recording start/end times, counts of processed and skipped records, and final status (Completed, Completed with errors, or Failed).
    • Per-record issues like missing required fields or unresolved references are logged with the correlation ID and resource ID for troubleshooting.
    • Critical failures such as transport or authentication errors mark the run as Failed and stop further processing.

    This logging enables effective monitoring and troubleshooting of FHIR sync runs to maintain data integrity and system reliability.

    A scheduled job runs an orchestration subflow that imports the four FHIR resources in dependency order, upserts each into the Healthcare Operations data model — matching primary records on the FHIR resource ID — and records the outcome in the FHIR Sync Log.

    Scheduled orchestration

    A scheduled job named FHIR Sync — Daily runs each day (by default at 03:00 instance time) and starts the Import FHIR Resources orchestration subflow. The orchestration subflow generates a correlation ID for the run and then runs the four per-resource import subflows in order. You can also start a run on demand with the scheduled job's Execute Now action.

    Dependency order

    The four resources are imported in an order that respects cross-resource references, and the run stops if an earlier resource fails:

    1. Organizations — must exist before locations and practitioner roles can reference them.
    2. Locations — reference their managing organization.
    3. Practitioners — become users that practitioner roles reference.
    4. PractitionerRoles — reference both an organization and a practitioner, so they import last.

    Idempotent upsert

    Each FHIR resource is matched to its primary Healthcare record by its FHIR logical ID, stored as external_id on the Healthcare (HCLS) Organization, Location, and Practitioner tables. Related records that have no external_id column — business locations, users, and service organization memberships — are matched on their natural keys instead, such as a user by email or a membership by its organization-and-user pair. Re-importing the same resource updates the existing records rather than creating duplicates, so repeated runs are safe. For the full field-by-field mapping, see FHIR-to-HCLS field mappings.

    Initial load and delta sync

    The first run performs a full load of all four resources. Each subsequent run reads the timestamp of the previous successful run from the FHIR Sync Log and requests only resources changed since then, so routine syncs transfer only deltas.

    Logging and error handling

    Each run writes one FHIR Sync Log row per resource type, all sharing the run's correlation ID. A row records the start and end times, processed and skipped counts, and a final status of Completed, Completed with errors, or Failed. Per-record skips — such as a resource missing a required field or an unresolvable reference — are logged to the system log with the correlation ID and FHIR ID, while transport or authentication failures set the row status to Failed and stop the run. For details, see Monitor and troubleshoot FHIR sync runs.