PersonRegistry.GetDemographics

From Wiki for HL7 Norge
Jump to: navigation, search

Operation-level Profile

Operation Name PersonRegistry.GetDemographics
Purpose Description To query (using a known identifier, e.g. F/D/FH-number) the person registry for the demographic details of a single person.

Note that it is the expectation that any application that (re-)activates a person record should use the GetDemographics service to get hold of the latest data. Part of the data returned may be an indication that (for example) the D-number used has now been merged with an F-Number.
See below for storyboards that illustrate the purpose of this operation.

Logic Description The operation will match the supplied identifier, using an exact match, with the identifiers as known for persons it holds the demographics data of, and will return either 0 (in case there wasn't a match) or 1 matching records.

Should the supplied identifier be linked to a more preferrential/reliable identifier: the record associated with the more preferential/reliable patient id will be returned instead of the record associated with the supplied identifier. Alternate (less preferrable, less reliable) identifiers of the matching person will be included in the matching record.

Input/Output Input: Person Registry Get Demographics Query (PRPA_IN101307NO). The core of this model is the query parameter that holds the Person Identifier.

Output: Person Registry Get Demographics Query Response (PRPA_IN101308NO). The core of this model is formed by the Generic Person Model, inclusive of the linkages from other person identifiers to the main person class.
See below for details of the information models as well as examples.

Composition Role Business level service
Composition Member Capabilities None.
Keywords Demographics data, person, search, person identifier, Folkeregister
Version 5.0
Finalization Status within HL7 Norway For review
Custodian HL7 Norway

Purpose of the operation

The storyboard below demonstrates the retrieving the demographic data associated with a specified person identifier. The query will be either based on the F-number, the D-number or the FH-number.

Storyboard Diagram

File:PRPA ST101307NO.gif

Note that the service is represented by the actor on the right hand side of this diagram.

Textual Storyboard

Dr. Alan Admit, who has admitting privileges at Good Health Hospital, notified the GHH Registration Office that his patient, Adam Everyman, would arrive at the hospital at a scheduled time, and that his office had performed a pre-admit on Adam Everyman.

As part of the admitting process, the GHH Registration clerk Alice Admitter entered Mr. Everyman's person identifier and initiated a PersonRegistry.GetDemographics operation. The operation returned Mr. Everyman's current demographic information and Alice confirmed this information with Mr. Everyman as she completed the admission process.

Input/Output

The query (input) model contains the person identifier. The output format will contain the F-Number (and/or D-Number) of the person as well as the demographics details of the person.

Input/Output List
Person Registry Get Demographics Query PRPA_IN101307NO01
Person Registry Get Demographics Query Response PRPA_IN101308NO01


Note that the above interactions use the “NO” realm code, and not the original “UV”. The models used are (currently) 100% equivalent to the international models. By using the NO realm the artefact identifier can be used for versioning purposes at some future point in time.

Input Information Model

The model is defined in the form of two wrappers (which contain meta-data related to the information exchange; the Transmission Wrapper and the ControlAct Wrapper and a so-called payload model. The payload model of the query interaction is shown here:

Class Component Documentation
QueryByParameter queryId The queryId contains the unique identification of this query instance. See II for a description of the II data type used. The id contains the unique identification of this query instance.
@root contains an identification of the ‘unique query instance numbering mechanism as used by this particular sending software application’, and @extension contains the identifier created according to that numbering mechanism. @root contains the ‘namespace’ of the identifier as contained in @extension
Implementation note: re-use same @extension/@root as used to identify the message instance in the Transmission Wrapper, see the documentation of the wrappers.
  statusCode @code contains the fixed value ‘new’
  Other Any other elements not listed above, but shown in the diagram, are reserved for future use in Norway. Sending applications SHOULD not use these elements; receiving applications SHALL nor produce an error if these elements are present, and MAY ignore these elements if present.


Class Component Documentation
PersonIdentifier value Contains the person identifier. This is a unique identification of a person.

See Identification of Patients and Persons for guidance related to the identification of persons, and the II Data Type for documentation of the II data type.
@root contains an identification of the ‘unique personidentification mechanism’ (i.e. the OID for F-Number, D-Number, etc.), and @extension contains the identifier created according to that identification mechanism.

  semanticsText semanticsText contains the fixed value ‘Person.id’

Output Information Model

The model is defined in the form of two wrappers (which contain meta-data related to the information exchange; the Transmission Wrapper and the ControlAct Wrapper and a so-called payload model. The payload model of the response interaction is documented on the Generic Person Model page.

Error Handling

See Error Handling for a general discussion of how errors can be identified in the response.

The response may contain an indication of errors during the processing of the request. The error codes are taken from the PersonRegistryErrors coding system (managed/maintained by NHN), with OID 2.16.578.1.12.4.5.2.1.1.

In case of processing errors the value of Acknowledgement.typeCode will be set to "AE", and the value of the DetectedIssueEvent.code attribute will be set to one of the codes shown below.

Lvl Code Description Documentation
1 INVALPID Invalid person identifier (One of) the person identifier(s) is invalid (null, empty, or not a valid F-, D-, or FH-number [a checksum failure])
1 NONEXIST Non existing person identifier The person identifier doesn't exist (in the database of the recieving application).
1 SERVERROR Generic error Uncaught exception, either from code or database - will only occur if there is a bug in the link/unlink code.

XML Examples

Input Example

<?xml version="1.0" encoding="UTF-8"?>
<PRPA_IN101307NO01 ITSVersion="XML_1.0" xmlns="urn:hl7-org:v3" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:hl7-org:v3 ../schemas/PRPA_IN101307NO.xsd">
   <id extension="080618105502_8" root="2.16.578.1.34.1.805.1"/>
   <creationTime value="20080618105502"/>
   <versionCode code="NE2010NE"/>
   <interactionId extension="PRPA_IN101307NO01" root="2.16.840.1.113883.1.6"/>
   <processingCode code="P"/>
   <processingModeCode code="T"/>
   <acceptAckCode code="NE"/>
   <receiver typeCode="RCV">
      <device classCode="DEV" determinerCode="INSTANCE">
         <!-- Receiving software application. NHN Person Registry -->
         <id root="2.16.578.1.12.4.5.1.1"/>
      </device>
   </receiver>
   <sender typeCode="SND">
      <device classCode="DEV" determinerCode="INSTANCE">
         <id extension="805" root="2.16.578.1.34.1"/>
      </device>
   </sender>
   <controlActProcess  classCode="CACT" moodCode="EVN">
      <authorOrPerformer typeCode="AUT">
         <assignedPerson classCode="ASSIGNED">
            <id extension="987654" root="2.16.578.1.34.3.1"/>
         </assignedPerson>
      </authorOrPerformer>
      <queryByParameter>
         <queryId extension="080618105502_8" root="2.16.578.1.34.1.805.1"/>
         <statusCode code="new"/>
         <parameterList>
            <identifiedPersonIdentifier>
               <value root="2.16.578.1.12.4.1.4.1" extension="17109012343" assigningAuthorityName="F-Number"/>
               <semanticsText>IdentifiedPerson.id</semanticsText>
            </identifiedPersonIdentifier>
         </parameterList>
      </queryByParameter>
   </controlActProcess>
</PRPA_IN101307NO01>

Output Example

<?xml version="1.0" encoding="UTF-8"?>
<PRPA_IN101308NO01 ITSVersion="XML_1.0" xmlns="urn:hl7-org:v3" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="urn:hl7-org:v3 ../schemas/PRPA_IN101308NO.xsd">
   <id extension="9382923825" root="2.16.578.1.12.4.5.3.1.1"/>
   <creationTime value="20080618105503"/>
   <versionCode code="NE2010NO"/>
   <interactionId extension="PRPA_IN101308NO01" root="2.16.840.1.113883.1.6"/>
   <processingCode code="P"/>
   <processingModeCode code="T"/>
   <acceptAckCode code="NE"/>
   <receiver typeCode="RCV">
      <device classCode="DEV" determinerCode="INSTANCE">
         <id extension="805" root="2.16.578.1.34.1"/>
      </device>
   </receiver>
   <sender typeCode="SND">
      <device classCode="DEV" determinerCode="INSTANCE">
          <!-- Sending software application. NHN Person Registry -->
         <id root="2.16.578.1.12.4.5.1.1"/>
      </device>
   </sender>
   <acknowledgement typeCode="AA"/>
      <targetMessage>
         <id extension="080618105502_8" root="2.16.578.1.34.1.805.1"/>
      </targetMessage>
   </acknowledgement>
   <controlActProcess  classCode="CACT" moodCode="EVN">
      <authorOrPerformer typeCode="AUT">
         <assignedDevice classCode="ASSIGNED">
            <id root="2.16.578.1.12.4.5.1.1"/>
         </assignedDevice>
      </authorOrPerformer>
      <subject typeCode="SUBJ">
         <registrationEvent classCode="REG" moodCode="EVN">
            <id nullFlavor="UNK"/>
            <statusCode code="active"/>
            <subject1 typeCode="SBJ">
               <identifiedPerson classCode="IDENT">
                  <id root="2.16.578.1.12.4.1.4.1" extension="17109012343" assigningAuthorityName="F-Number"/>
                  <statusCode code="active"/>
                  <identifiedPerson>
                     <id root="2.16.578.1.12.4.1.4.1" extension="17109012343"/>
                     <name use="L">
                        <given>Ole</given>
                        <given>Helge</given>
                        <family>Duck</family>
                     </name>				
                     <administrativeGenderCode code="M" codeSystem="2.16.840.1.113883.5.1"/>
                     <birthTime value="19901017"/>
                     <addr use="HP">
                        <streetAddressLine>Apalveien 13</streetAddressLine>
                        <postalCode>3162</postalCode>
                        <city>Andebu</city>
                     </addr>
                     <maritalStatusCode code="1" codeSystem="2.16.578.1.34.1000.6" displayName="Ugift"/>
                  </identifiedPerson>
                  <identifiedBy typeCode="IDENT">
                     <statusCode code="active"/>
                     <otherIdentifiedPerson classCode="IDENT">
                        <id root="2.16.578.1.12.4.1.4.2" extension="64109642356"
                            assigningAuthorityName="D-Number"/>
                     </otherIdentifiedPerson>
                  </identifiedBy>
               </identifiedPerson>
            </subject1>
            <custodian typeCode="CST">
               <assignedEntity classCode="ASSIGNED">
                  <id root="2.16.578.1.12.4.1.4.101" extension="983658725"/>
               </assignedEntity>
            </custodian>
         </registrationEvent>
      </subject>
      <queryAck>
         <queryId extension="080618105502_8" root="2.16.578.1.34.1.805.1"/>
         <queryResponseCode code="OK"/>
         <resultCurrentQuantity value="1"/>
         <resultRemainingQuantity value="0"/>
      </queryAck>
   </controlActProcess>
</PRPA_IN101308NO01>


Example #2: given the following sequence of link operations:

  1. At 2010-01-02 03:04:05: Link 01011228301 to X
  2. At 2010-01-02 03:04:06: Link 01011932963 to X
  3. At 2010-01-02 03:04:07: Unlink 01011932963 from X

A GetDemographics on 01011228301 will "redirect" and show X instead, with these identifiedBy elements:

<identifiedBy typeCode="IDENT">
    <statusCode code="active"/>
    <effectiveTime>
         <low value="20100102030405"/>
    </effectiveTime>
    <otherIdentifiedPerson classCode="IDENT">
         <id root="2.16.578.1.12.4.1.4.1" extension="01011228301" 
            assigningAuthorityName="F-Number"/>
    </otherIdentifiedPerson>
</identifiedBy>
<identifiedBy typeCode="IDENT">
    <statusCode code="cancelled"/>
    <effectiveTime>
         <low value="20100102030406"/>
         <high value="20100102030407"/>
    </effectiveTime>
    <otherIdentifiedPerson classCode="IDENT">
         <id root="2.16.578.1.12.4.1.4.1" extension="01011932963" 
           assigningAuthorityName="F-Number"/>
    </otherIdentifiedPerson>
</identifiedBy>