fhir-human-services-directory
1.0.0-ballot - STU Ballot US

This page is part of the FHIR IG Human Services Directory (v1.0.0-ballot: STU 1 Ballot 1) based on FHIR R4. . For a full list of available versions, see the Directory of published versions

Resource Profile: HSDSOrganization - Mappings

Active as of 2022-12-08

Mappings for the hsds-Organization resource profile.

Mappings for ServD (http://www.omg.org/spec/ServD/1.0/)

HSDSOrganization
OrganizationOrganization
   identifier./Identifiers, n/a
      system./IdentifierType
      value./Value
      period./StartDate and ./EndDate
      assigner./IdentifierIssuingAuthority
   identifier (NPI)./Identifiers, n/a
   identifier (CLIA)./Identifiers, n/a
   active./Status (however this concept in ServD more covers why the organization is active or not, could be delisted, deregistered, not operational yet) this could alternatively be derived from ./StartDate and ./EndDate and given a context date.
   typen/a
   name.PreferredName/Name, ./PrimaryAddress and ./OtherAddresses
   telecom./ContactPoints
      system./ContactPointType
      value./Value
      use./ContactPointPurpose
      period./StartDate and ./EndDate
   address./PrimaryAddress and ./OtherAddresses, n/a
      use./AddressPurpose
      line./StreetAddress (newline delimitted)
      city./Jurisdiction
      state./Region, ./Sites
      postalCode./PostalIdentificationCode
      country./Country
      period./StartDate and ./EndDate
   partOfn/a
   contact
      telecom
         system./ContactPointType
         value./Value
         use./ContactPointPurpose
         period./StartDate and ./EndDate

Mappings for HL7 v2 Mapping (http://hl7.org/v2)

HSDSOrganization
Organization(also see master files messages)
   identifierXON.10 / XON.3
      useN/A
      typeCX.5
      systemCX.4 / EI-2-4
      valueCX.1 / EI.1
      periodCX.7 + CX.8
      assignerCX.4 / (CX.4,CX.9,CX.10)
   identifier (NPI)XON.10 / XON.3
   identifier (CLIA)XON.10 / XON.3
   activeNo equivalent in HL7 v2
   typeNo equivalent in v2
   nameXON.1
   telecomORC-22?
      systemXTN.3
      valueXTN.1 (or XTN.12)
      useXTN.2 - but often indicated by field
      rankn/a
      periodN/A
   addressORC-23?
      useXAD.7
      typeXAD.18
      textXAD.1 + XAD.2 + XAD.3 + XAD.4 + XAD.5 + XAD.6
      lineXAD.1 + XAD.2 (note: XAD.1 and XAD.2 have different meanings for a company address than for a person address)
      cityXAD.3
      districtXAD.9
      stateXAD.4
      postalCodeXAD.5
      countryXAD.6
      periodXAD.12 / XAD.13 + XAD.14
   partOfNo equivalent in HL7 v2
   contact
      namePID-5, PID-9
      telecomPID-13, PID-14
         systemXTN.3
         valueXTN.1 (or XTN.12)
         useXTN.2 - but often indicated by field
         rankn/a
         periodN/A
      addressPID-11

Mappings for RIM Mapping (http://hl7.org/v3)

HSDSOrganization
OrganizationEntity. Role, or Act, Organization(classCode=ORG, determinerCode=INST)
   meta
      idn/a
      extensionn/a
   textAct.text?
   containedN/A
   modifierExtensionN/A
   identifier.scopes[Role](classCode=IDENT)
      idn/a
      extensionn/a
      useRole.code or implied by context
      typeRole.code or implied by context
      systemII.root or Role.id.root
      valueII.extension or II.root if system indicates OID or GUID (Or Role.id.extension or root)
      periodRole.effectiveTime or implied by context
      assignerII.assigningAuthorityName but note that this is an improper use by the definition of the field. Also Role.scoper
   identifier (NPI).scopes[Role](classCode=IDENT)
   identifier (CLIA).scopes[Role](classCode=IDENT)
   active.status
   type.code
   name.name
   alias.name
   telecom.telecom
      idn/a
      extensionn/a
      system./scheme
      value./url
      useunique(./use)
      rankn/a
      period./usablePeriod[type="IVL<TS>"]
   address.address
      idn/a
      extensionn/a
      useunique(./use)
      typeunique(./use)
      text./formatted
      lineAD.part[parttype = AL]
      cityAD.part[parttype = CTY]
      districtAD.part[parttype = CNT | CPA]
      stateAD.part[parttype = STA]
      postalCodeAD.part[parttype = ZIP]
      countryAD.part[parttype = CNT]
      period./usablePeriod[type="IVL<TS>"]
   partOf.playedBy[classCode=Part].scoper
   contact.contactParty
      idn/a
      modifierExtensionN/A
      purpose./type
      name./name
      telecom./telecom
         idn/a
         extensionn/a
         system./scheme
         value./url
         useunique(./use)
         rankn/a
         period./usablePeriod[type="IVL<TS>"]
      address./addr
   endpointn/a

Mappings for FiveWs Pattern Mapping (http://hl7.org/fhir/fivews)

HSDSOrganization
Organization
   identifierFiveWs.identifier
   identifier (NPI)FiveWs.identifier
   identifier (CLIA)FiveWs.identifier
   activeFiveWs.status
   typeFiveWs.class

Mappings for HSDS (HSDS)

This section describes the way HSDS version 2.0.1 elements are mapped from HSDS tables to the FHIR Organization profile. The left hand column represents the FHIR Organization element name, the right column contains the HSDS table.element followed by its description within parenthesis. Comments related to the mapping may follow the HSDS element description.

HSDSOrganization
Organization
   idorganization.id Note: Each organization must have a unique system identifier in the source system.
   metaNote: The HSDS metadata table contains a record of the changes that have been made to the data in order to maintain provenance information.
      idmetadata.id Note: This data element may be ignored as having the id for the date metadata isn't essential. If populated, it should be id corresponding to the latest action date for given organization as described below.
      lastUpdatedmetadata.last_action_date Note: The date when data was changed. Since there may be more than one metadata record for each organization, the latest max(last_action_date) needs to be used from metadata where (FHIR) Organization.id = (HSDS) metadata.resource_id.
   languageNo Source. May be excluded from the mapping. Note: This data element in FHIR is referring to language for the resource context and not the language for the communication for given service or location.
   textNo Source. May be excluded from the mapping. Note: This DomainResource.text is meant for textual summary of the resource so organization description is mapped to the org-description extension added by Plan-Net profile.
   extension (qualification)extension[qualification]:code.url = 'code' extension[qualification]:code.valueCodeableConcept.text = service.accreditations Note: This is a GAP in HSDS that can be resolved by having qualifications collected at the organization level. As a workaround, suggested mapping uses the unique set of accreditations from service and concatenated for the organization level as described below.
   extension (org-description)organization.description Note: This Plan-Net profile added this extension for organization description as opposed to using DomainResource.text data element which is meant for textual summary of the resource.
   identifier
      idNo Source. May be excluded from the mapping. Note: This data element may be ignored as having the id for the identifier record isn't essential and is not available in HSDS since the tax ID is directly on the organization table.
      useFixed value = 'official' Note: Since the organization business identifier in HSDS is organization.tax id which is used for official purpose, this element is to be set with a fixed value 'official' drawn from the code system IdentifierUse http://hl7.org/fhir/identifier-use.
      typeFixed value = 'TAX' Note: Since the organization business identifier in HSDS is organization.tax id which is used for the tax, this element is to be set with a fixed value 'TAX' drawn from the IdentifierType code system – http://terminology.hl7.org/CodeSystem/v2-0203 [an HL7-defined code system of concepts specifying type of identifier].
      systemFixed value = 'urn:us:gov:irs' Note: Since the organization business identifier in HSDS is organization.tax id which is issued by IRS, this element is to be set with a fixed value with IRS URN.
      valueorganization.tax_id Note: This is the only business identifier in HSDS at this time.
      periodorganization.year_incorporated Note: HSDS organization.year_incorporated may not always be the same as when the TAX ID was issued (especially if a company merged or split). Technically year_incorporated is a GAP in FHIR and should be added as an extension. Also the effective date of the identifier (mapped to period here) is GAP in HSDS. But until both of those GAPs are addressed, the above mapping is proposed as a work around.
      assignerFixed value = 'www.irs.gov' Note: This is GAP in HSDS but it can be implicitly inferred. Since the organization business identifier in HSDS is organization.tax id which is issued by IRS, this element is to be set with a fixed value with IRS website link as a reference.
   activeFixed value = 'true' Note: HSDS organization does not have a status but this is required in FHIR so fixed value is proposed to indicate that organization is active.
   typeFixed values: type.code = 'atyprv' and type.system = 'http://hl7.org/fhir/us/DaVinci-pdex-plan-net/ValueSet/OrgTypeVS' Note: This is a GAP in HSDS but required per Plan-Net profile. Among the allowable codes, 'atyprv' is proposed to represent 'Providers that do not provide healthcare' as the most appropriate for the human services providers.
   nameorganization.name
   aliasorganization.alternate_name Note: Since there is only one alternate name in HSDS but the alias is an array (list) in FHIR, this will map to the first occurrence of the array.
   telecomNote: This FHIR structure contains contact details of the organization using the ContactPoint datatype (Details for all kinds of technology-mediated contact points for a person or organization, including telephone, email, etc.).
      idNo Source. May be excluded from the mapping. Note: This data element may be ignored as having the id for the telecom record isn't essential and not always available in the HSDS (e.g. phone id is available but there is no separate id for email or website URL).
      extension (contactpoint-availabletime)No Source. Note: This is a GAP in HSDS. This FHIR extension is added by Plan-Net profile and represents available hours for the telecom (e.g. customer service phone hours from 8AM-6PM M-F). There is no equivalent mapping to this data element in HSDS since the HSDS schedule table contains details of when a service or location is open, and is not a phone line associated with an organization.
      extension (via-intermediary)No Source. Note: This is GAP in HSDS. This FHIR extension added by Plan-Net profile represents a reference to an alternative point of contact. HSDS does not have the source data to represent 'intermediary' as that implies some sort of organizational relationship.
      systemFor Phone: if phone.type = 'voice' then system = 'phone' if phone.type = 'cell' then system = 'phone' if phone.type = 'fax' then system = 'fax' if phone.type = 'pager' then system = 'pager' if phone.type = 'text' then system = 'sms' if phone.type = 'textphone' then system = 'sms' if phone.type = 'video' then system = 'other' For Email: Fixed value = 'email' For Website URL: Fixed value = 'url' Note: There are multiple sources in HSDS for the telecom in FHIR so the system will be populated based on phone.type mapping or fixed value of 'email' or 'url' depending on the data populated. Drawn from the ContactPointSystem value set [http://hl7.org/fhir/ValueSet/contact-point-system]
      valueFor Phone: value = phone.number For Email, value = organization.email For Website URL: value = organization.url Note: For phone, HSDS organization linkage is to HSDS phone table using organization.id = phone.organization_id.
      useFixed value = 'work' Note: This is a GAP in HSDS but since it is for work related information, it is possible to set this to 'work' drawn from the ContactPointUse value set http://hl7.org/fhir/R4/valueset-contact-point-use.html.
      rankNo Source. Note: This a GAP in HSDS. In FHIR, it is used to specify a preferred order in which to use a contact point. The parent Plan-Net profile indicates this is a Must Support element but is optional, So it can be excluded since there is no source.
      periodNo Source. May be excluded from the mapping. Note: This is a GAP in HSDS. In FHIR, this data element captures the time period when the contact point was/is in use. But it can be excluded since there is no source and it is optional.
   addressNote: HSDS does not have an address associated with the organization. So the Location table is used to capture address details associated with locations that are part of that organization. Two HSDS tables are used, one for postal_address, the other for physical_address. This linkage is based on organization.id = location.organization_id and location.id = address.location_id. If there are multiple locations and associated addresses, all of those can be included for organization level addresses since there is no indication to identify which location or address is primary to be used as organization address.
      idpostal_address.id or physical_address_id Note: This data element may be ignored as having the id for the address record isn't essential. If populated, it should be the id from one of the address tables that particular address is referring to.
      extension (geolocation)location.latitude Note: There is no location in HSDS at the organization level.
      useFixed value = 'work' Note: This is a GAP in HSDS but since it is for work related information, it is possible to set this to 'work' drawn from the AddressUse value set http://hl7.org/fhir/R4/valueset-address-use.html.
      typeFixed value = 'postal' or 'physical' Note: This is a GAP in HSDS but it can be inferred by which table is used as a source in the HSDS i.e. postal_address or physical_address respectively.
      textConcatenation of address_1, city, state_province, postal_code and country; all separated by comma (,) except dash (-) between state_province and postal_code. Note: The address data elements will be from postal_address or physical_address depending on which address is sourced. In FHIR, this element specifies the entire address as it should be displayed.
      linepostal_address.address_1 or physical_address.address_1 Note: address.line in FHIR is an array (list) so address_1 is populated in the first position of the array. If address_2 is available (although deprecated in HSDS), it may be populated in the second position of the array.
      citypostal_address.city or physical_address.city
      districtpostal_address.region or physical_address.region
      statepostal_address.state_province_code or physical_address.state_province_code
      postalCodepostal_address.postal_code or physical_address.postal_code
      countrypostal_address.country or physical_address.country
      periodNo Source. May be excluded from the mapping. Note: This a GAP in HSDS. In FHIR, this data element represents the time period when the address was in use for the organization.
   partOfNo Source. Note: This a GAP in HSDS. There is no concept of organization hierarchy in HSDS.
   contactNote: contact Table The HSDS contact table contains details of the named contacts associated with the organization. This linkage is based on FHIR organization.id = HSDS contact.organization_id. If there are multiple contacts, all of those can be included for organization level contacts in FHIR since there is no indication to identify which contact is primary.
      idcontact.id Note: This data element may be ignored as having the id for the contact record isn't essential.
      extensioncontact.department Note: This is a GAP in FHIR. Proposed publishing a new StructureDefinition for this extension, e.g., http://hl7.org/fhir/us/FHIR-IG-Human-Services-Directory/StructureDefinition/contact-department
      purposeNo Source. May be excluded from the mapping. Note: This is a GAP In HSDS. In FHIR, this element is used to indicate the purpose of which the contact can be reached.
      namecontact.name
      telecom
         idNo Source. May be excluded from the mapping. Note: This data element may be ignored as having the id for the telecom record isn't essential and not always available in the HSDS (e.g. phone id is available but there is no separate id for email).
         extension (contactpoint-availabletime)No Source. May be excluded from the mapping. Note: This is a GAP in HSDS. This FHIR extension is added by Plan-Net profile and represents available hours for the telecom (e.g. customer service phone hours from 8AM-6PM M-F). There is no equivalent mapping to this data element in HSDS since the HSDS schedule table contains details of when a service or location is open, and is not a phone line associated with a contact.
         extension (via-intermediary)No Source. May be excluded from the mapping. Note: This is GAP in HSDS. This FHIR extension added by Plan-Net profile represents a reference to an alternative point of contact. HSDS does not have the source data to represent 'intermediary' as that implies some sort of contact relationship.
         systemFor Phone: if phone.type = 'voice' then system = 'phone' if phone.type = 'cell' then system = 'phone' if phone.type = 'fax' then system = 'fax' if phone.type = 'pager' then system = 'pager' if phone.type = 'text' then system = 'sms' if phone.type = 'textphone' then system = 'sms' if phone.type = 'video' then system = 'other' For Email: Fixed value = 'email' Note: There are multiple sources in HSDS for the telecom in FHIR so the system will be populated based on phone.type mapping or fixed value of 'email' depending on the data populated.
         valueFor Phone: value = phone.number For Email, value = conact.email Note: For phone, HSDS contact table will be linked to the phone table using contact.id = phone.contact_id.
         useFixed value = 'work' Note: This is a GAP in HSDS but since it is for work-related information, it is possible to set this to 'work' drawn from the ContactPointUse value set http://hl7.org/fhir/R4/valueset-contact-point-use.html
         rankNo Source. May be excluded from the mapping. Note: This is a GAP in HSDS. In FHIR, it is used to specify a preferred order in which to use a contact point. The parent Plan-Net profile indicates this is a Must Support element but is optional, So it can be excluded since there is no source.
         periodNo Source. May be excluded from the mapping. Note: This is a GAP in HSDS. In FHIR, this data element captures the time period when the contact point was/is in use. But it can be excluded since there is no source and it is optional.
      addressGAP in HSDs. May need to keep track of a contact party's address for contacting, billing or reporting requirements.
   endpointNo Source. Note: This is for the technical implementation of web services for the organization and it is not for source-specific business data. It is marked as Must Support though optional in the Plan-Net profile. At this point, no organizayion specific web services have been identified so it may be ignored.