FHIR-to-HCLS field mappings

  • 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 FHIR-to-HCLS field mappings

    This document details how the Healthcare Operations HL7 FHIR Integration maps key FHIR R4 resource fields to ServiceNow Healthcare and Life Sciences (HCLS) target tables. It describes the upsert process that matches records by FHIR logical IDs or natural keys, ensuring synchronization between FHIR data and HCLS platform records. The focus is on four primary FHIR resource types: Organization, Location, Practitioner, and PractitionerRole.

    Show full answer Show less

    Key Features

    • Organization Mapping: FHIR Organizations map to snhclsorganization and classify into internal or external business locations using classification tables. The FHIR id is stored as externalid. Critical fields like name are mandatory, while type drives classification and defaults to “other” if missing. Parent organizations are linked by partOf references, with limited hierarchy recovery.
    • Location Mapping: FHIR Locations upsert into snhclslocation and platform cmnlocation tables. Relationships to parent locations and organizations are resolved and linked. Address and position data anchor the platform location. The managingOrganization association is created if resolvable.
    • Practitioner Mapping: FHIR Practitioners populate snhclspractitioner and the platform sysuser table, with login enabled for imported users. The id field maps to externalid, and the telecom email serves as the unique user identifier—practitioners without email are skipped. Name components are imported with defaults where missing. Each practitioner is granted the snhco.careteammember role.
    • PractitionerRole Mapping: FHIR PractitionerRoles create entries in sncsmserviceorganizationmember and sncsmsvcorgmemberresponsibility, linking practitioners to organizations as care team members. Practitioner and organization references must resolve correctly; otherwise, roles are skipped. Role codes and specialties are not mapped in this release.

    Important Considerations

    • Not all FHIR fields are mapped—practitioner NPIs, additional identifiers, and PractitionerRole specialties and codes are intentionally excluded in this release.
    • Parent hierarchies support only one level of recovery for missing references; deeper gaps are logged but not resolved automatically.
    • Practitioner records require valid email addresses to be imported and linked to user accounts.
    • Location and organization associations are created only when references can be resolved; unresolved associations are logged but do not block record upserts.

    Benefits for ServiceNow Customers

    By leveraging these mappings, ServiceNow customers can efficiently synchronize core healthcare operational data from FHIR sources into the HCLS platform. This alignment enables unified management of organizations, locations, practitioners, and care team memberships within ServiceNow, facilitating streamlined healthcare operations and integrated workflows. Understanding these mappings helps customers anticipate data behavior during imports and supports troubleshooting or customization efforts related to healthcare data integration.

    For each of the four FHIR R4 resources, the Healthcare Operations HL7 FHIR Integration maps FHIR fields to Healthcare Operations target tables and upserts records — matching the primary HCLS record on the FHIR resource ID (stored as an external identifier) and related records on their natural keys.

    Each resource's primary record is matched 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. The tables below summarize the principal field mappings; some fields are populated on related platform tables as a side effect of the upsert.

    Some FHIR data is intentionally not mapped in this release: practitioner NPI and other identifiers (the FHIR logical ID serves as the external identifier), and PractitionerRole role codes and specialties.

    Organization

    FHIR Organizations upsert into sn_hcls_organization and, based on the organization classification decision table, into either sn_csm_business_location_internal or sn_csm_business_location_external.

    FHIR field Target field Notes
    id sn_hcls_organization.external_id Upsert key.
    name sn_hcls_organization.name Required; the record is skipped if it is missing.
    type sn_hcls_organization.org_type Defaults to other if missing or unrecognized. Drives the internal/external business location classification.
    partOf sn_hcls_organization.parent Resolved to a parent organization by external ID. One level of missing parent is recovered; deeper hierarchy gaps are logged.
    address, telecom Business location address and contact fields Written to the internal or external business location record.

    Location

    FHIR Locations upsert into sn_hcls_location and the platform cmn_location table, and optionally create an organization-location association.

    FHIR field Target field Notes
    id sn_hcls_location.external_id Upsert key.
    name sn_hcls_location.name, cmn_location.name Required.
    status sn_hcls_location.status Maps directly (active, suspended, inactive).
    physicalType sn_hcls_location.physical_type Mapped where a matching HCLS value exists; left empty otherwise.
    address, position cmn_location address and coordinate fields The platform location is anchored to the HCLS location.
    partOf sn_hcls_location.parent_location, cmn_location.parent Resolved by external ID, with one level of parent recovery. The parent is set on both the Healthcare Location and the platform location.
    managingOrganization sn_hcls_organization_location_association Creates the association if the organization resolves; otherwise the association is skipped and logged, and the location still upserts.

    Practitioner

    FHIR Practitioners upsert into sn_hcls_practitioner and the platform sys_user table, and each practitioner is granted the care-team-member role.

    FHIR field Target field Notes
    id sn_hcls_practitioner.external_id Upsert key.
    telecom (email) sys_user.user_name, sys_user.email Required; normalized and used to match or create the user. Practitioners without an email are skipped.
    name (given, family, prefix, suffix, text) Practitioner and user name fields Given name defaults to Unknown if missing, and the run is marked Completed with errors.
    gender sn_hcls_practitioner.gender Mapped to HCLS values; defaults to not-disclosed if missing or unknown.
    birthDate, telecom (phone), address, active Corresponding practitioner and user fields Imported users have login enabled; admins set credentials separately.
    (role grant) sys_user_has_role Each practitioner is granted the sn_hco.care_team_member role.

    PractitionerRole

    FHIR PractitionerRoles upsert into sn_csm_service_organization_member and sn_csm_svc_org_member_responsibility, placing a practitioner on a care team for an organization.

    FHIR field Target field Notes
    practitioner.reference sn_csm_service_organization_member.user Resolved through the Healthcare Practitioner record to the user. The role is skipped if the practitioner is not found.
    organization.reference sn_csm_service_organization_member.service_organization Resolved through the Healthcare Organization to its business location. The role is skipped if the organization is not resolvable.
    (responsibility) sn_csm_svc_org_member_responsibility.type Set to the Care Team Member responsibility for every imported role.
    code, specialty Not mapped FHIR role codes and specialties are not captured in this release.
    location Not used The role's location array is not used to infer organization membership.