--- sourceDocument: Australia Healthcare and Life Sciences sourceDocumentLink: https://www.servicenow.com/docs/r/australia/healthcare-life-sciences Release : - australia ft:locale : - en-US ft:publication_title : - Australia Healthcare and Life Sciences ft:clusterId : - hcls bundleId : - hcls workflow : - Customer and Industry --- # FHIR-to-HCLS field mappings # FHIR-to-HCLS field mappings {#ariaid-title1} Release version: Australia Updated June 16, 2026 ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 2 minutes to read Summarize ![AI sparkle icon](https://servicenow.com/docs/portal-asset/ai-sparkle-icon) 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 The Healthcare Operations HL7 FHIR Integration for the Australia release (updated June 16, 2026) enables ServiceNow customers to synchronize data from four key FHIR R4 resources---Organization, Location, Practitioner, and PractitionerRole---into the Healthcare Operations (HCLS) tables. This integration maps FHIR fields to corresponding HCLS target tables and upserts records by matching primary records using the FHIR logical ID as an external identifier, or natural keys for related records without an external ID. The process supports creating and updating healthcare-related organizational, locational, and practitioner data within ServiceNow. Show full answer Show less ## Key Features * **Organization Mapping:** FHIR Organization resources upsert into `snhclsorganization` and classify business locations as internal or external based on organization type. Parent organizations are resolved by external ID with limited hierarchy recovery. Address and contact details populate business location tables. * **Location Mapping:** FHIR Locations upsert into `snhclslocation` and the platform `cmnlocation` table. Location status, physical type, address, and coordinates are mapped. Parent location relationships are resolved one level deep, and managing organization associations are created when possible. * **Practitioner Mapping:** FHIR Practitioners upsert into `snhclspractitioner` and the platform `sysuser` table. Practitioners must have an email to be imported. Their names, gender, birth date, contact info, and active status are mapped. Each practitioner is assigned the `snhco.careteammember` role automatically. * **PractitionerRole Mapping:** FHIR PractitionerRoles upsert into service organization member and responsibility tables, linking practitioners to care teams within organizations. Practitioner and organization references must resolve correctly; otherwise, roles are skipped. Role codes and specialties are not mapped. ## Important Considerations * Some FHIR data such as practitioner NPI identifiers and PractitionerRole specialties and role codes are intentionally not mapped in this release. * Records missing required fields (e.g., Organization name, Practitioner email) are skipped or logged with errors. * Parent entity relationships support one level of missing parent recovery; deeper hierarchy gaps are logged for troubleshooting. * Upsert keys rely primarily on FHIR logical IDs stored as external identifiers to ensure accurate matching and updates. ## What Customers Can Expect By implementing this FHIR-to-HCLS field mapping integration, ServiceNow customers can efficiently import and synchronize healthcare operational data from FHIR R4 resources into the ServiceNow Healthcare Operations application. This ensures consistent, up-to-date organizational, location, and practitioner information within the platform, enabling better care team management and operational insights. Customers should prepare to handle skipped records due to missing required fields and review logs for any unresolved parent entity hierarchies. 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 {#hco-fhir-field-mappings__hco-fhir-mappings-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`. {#hco-fhir-field-mappings__hco-fhir-mappings-organization__entry__3} | 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 {#hco-fhir-field-mappings__hco-fhir-mappings-location} FHIR Locations upsert into `sn_hcls_location` and the platform `cmn_location` table, and optionally create an organization-location association. {#hco-fhir-field-mappings__hco-fhir-mappings-location__entry__3} | 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 {#hco-fhir-field-mappings__hco-fhir-mappings-practitioner} FHIR Practitioners upsert into `sn_hcls_practitioner` and the platform `sys_user` table, and each practitioner is granted the care-team-member role. {#hco-fhir-field-mappings__hco-fhir-mappings-practitioner__entry__3} | 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 {#hco-fhir-field-mappings__hco-fhir-mappings-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. {#hco-fhir-field-mappings__hco-fhir-mappings-practitionerrole__entry__3} | 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. | | location | Not used | The role's location array is not used to infer organization membership. | [ ]