Difference between revisions of "201605 Conditional Reference Connectathon Proposal"

From HL7Wiki
Jump to navigation Jump to search
(Created page with " May 2016 Proposals __NOTOC__ =Conditional Reference= ==Submitting WG/Project/Implementer Group== ==Justification== ...")
 
Line 11: Line 11:
  
 
In many scenarios, FHIR resources can be uniquely (re-)identified by their common business identifier
 
In many scenarios, FHIR resources can be uniquely (re-)identified by their common business identifier
(e.G.). Since FHIR resources however can only be referenced by their server assigned resource id, referencing to reources that are known by the client only by theri business identifier requires an additional step to retreivethe resource matching that business identifier, extracting the resource ID and then create a reference accordingly.
+
(e.G.). Since FHIR resources however can only be referenced by their server assigned resource id, referencing to resources that are known by the client only by their business identifier requires an additional step to retreive the resource matching that business identifier, extracting the resource ID and then create a reference accordingly.
  
In the context of Transactions, it is required to include bogus Resources with conditional create/update requests in order to be able to create references.
+
In the context of Transactions, it is required to include bogus Resources with conditional create requests in order to be able to create references. This may cause undesired side effects because the client is forced to use create verb on resources it actually means to read. Transactions may fail due to lack of client write permissions even though the client does not actually want to write anything.
  
The proposal has been made to allow conditional references with the same syntax as conditional updates.
+
Example: The Client wants to create an Observation linked to the Patient with business identifier 12345.
 +
The Client does not have write permissions on Patient resources.
 +
The Transaction Bundle would need to include the Patient resource with a uuid and a create condition in order to invoke the server's responsibility to
 +
a) search for a patient that matches the condition
 +
b) replace the uuid and all references to it in the transaction bundle with the actual id
  
Example:
+
  <Bundle xmlns="http://hl7.org/fhir">
 
+
  <id value="20160113160203" />
A client App scans a barcode encoding a patient ID. Instead of searching for the patient resource on the server and extracting the resource id in order to create Observations referencing the patient, the client can create an Observation as follows:
+
  <type value="transaction" />
 +
  <entry>
 +
  <fullUrl value="urn:uuid:653a9d22-b6c1-44cd-55a0-3ce35d574642" />
 +
  <resource>
 +
  <Patient>
 +
  <identifier>
 +
  <value value="12345" />
 +
  </identifier>
 +
  </Patient>
 +
  </resource>
 +
  <request>
 +
  <method value="CREATE" />
 +
  <if-none-exixts="Patient?identifier=12345" />
 +
  </request>
 +
  </entry>
 +
  <entry>
 +
  <fullUrl value="urn:uuid:c72aa430-2ddc-456e-7a09-dea8264671d8" />
 +
  <resource>
 +
  <Observation>
 +
                <subject>
 +
                                  <reference value="urn:uuid:653a9d22-b6c1-44cd-55a0-3ce35d574642"/>
 +
                          </subject>
 +
                        </Observation>
 +
            </resource>
 +
            <request>
 +
                  <method value="CREATE" />
 +
            </request>
 +
        </entry>
 +
  </Bundle>
 +
  
 +
The transcaction would fail if
 +
a) no patient matches the create condition and the subsequent create action runs into an error due to insufficient client permissions
 +
b) multiple patients match the create condition
 +
The proposal has been made to allow conditional references with the same syntax as conditional updates.
  
<Observation>
 
  <subject>
 
    <reference value="Patient?identifier=12345"/>
 
  </subject>
 
</Observation>
 
  
 +
As a more intuitive approach, this Connectathon Track suggests to allow the conditional url otherwise placed in the if-none-exists attribute directly in the patient reference:
 +
<source lang="xml">
 +
  <Bundle xmlns="http://hl7.org/fhir">
 +
  <id value="20160113160203" />
 +
  <type value="transaction" />
 +
  <entry>
 +
  <fullUrl value="urn:uuid:c72aa430-2ddc-456e-7a09-dea8264671d8" />
 +
  <resource>
 +
  <Observation>
 +
              <subject>
 +
                                  <reference value="Patient?identifier=12345"/>
 +
                          </subject>
 +
                        </Observation>
 +
          </resource>
 +
            <request>
 +
                <method value="CREATE" />
 +
            </request>
 +
        </entry>
 +
  <Bundle>
 +
</source>
  
 
The server is expected to
 
The server is expected to
 
a) replace the conditional reference by the actual id of the one resource that matches the criteria  
 
a) replace the conditional reference by the actual id of the one resource that matches the criteria  
b) return an error (412 - precondition failed) if no resource matches the criteria
+
b) return an error (412 - precondition failed) if no resource matches the criteria (..or rather: 404???)
 
c) return an error (412 - precondition failed) if multiple resources matches the criteria
 
c) return an error (412 - precondition failed) if multiple resources matches the criteria
  

Revision as of 15:08, 12 February 2016


Conditional Reference

Submitting WG/Project/Implementer Group

Justification

In many scenarios, FHIR resources can be uniquely (re-)identified by their common business identifier (e.G.). Since FHIR resources however can only be referenced by their server assigned resource id, referencing to resources that are known by the client only by their business identifier requires an additional step to retreive the resource matching that business identifier, extracting the resource ID and then create a reference accordingly.

In the context of Transactions, it is required to include bogus Resources with conditional create requests in order to be able to create references. This may cause undesired side effects because the client is forced to use create verb on resources it actually means to read. Transactions may fail due to lack of client write permissions even though the client does not actually want to write anything.

Example: The Client wants to create an Observation linked to the Patient with business identifier 12345. The Client does not have write permissions on Patient resources. The Transaction Bundle would need to include the Patient resource with a uuid and a create condition in order to invoke the server's responsibility to a) search for a patient that matches the condition b) replace the uuid and all references to it in the transaction bundle with the actual id

 <Bundle xmlns="http://hl7.org/fhir">
 <id value="20160113160203" />
 <type value="transaction" />
 <entry>
 <fullUrl value="urn:uuid:653a9d22-b6c1-44cd-55a0-3ce35d574642" />
 <resource>
 <Patient>
 <identifier>
 <value value="12345" />
 </identifier>
 </Patient>
 </resource>
 <request>
 <method value="CREATE" />
 <if-none-exixts="Patient?identifier=12345" />
 </request>
 </entry>
 <entry>
 <fullUrl value="urn:uuid:c72aa430-2ddc-456e-7a09-dea8264671d8" />
 <resource>
 <Observation>
                <subject>
                                 <reference value="urn:uuid:653a9d22-b6c1-44cd-55a0-3ce35d574642"/>
                          </subject>
                       </Observation>
            </resource>
            <request>
                  <method value="CREATE" />
            </request>
       </entry>
 </Bundle>


The transcaction would fail if a) no patient matches the create condition and the subsequent create action runs into an error due to insufficient client permissions b) multiple patients match the create condition The proposal has been made to allow conditional references with the same syntax as conditional updates.


As a more intuitive approach, this Connectathon Track suggests to allow the conditional url otherwise placed in the if-none-exists attribute directly in the patient reference: <source lang="xml">

 <Bundle xmlns="http://hl7.org/fhir">
 <id value="20160113160203" />
 <type value="transaction" />
 <entry>
 <fullUrl value="urn:uuid:c72aa430-2ddc-456e-7a09-dea8264671d8" />
 <resource>
 <Observation>
              <subject>
                                 <reference value="Patient?identifier=12345"/>
                          </subject>
                       </Observation>
          </resource>
            <request>
               <method value="CREATE" />
            </request>
       </entry>
 <Bundle>

</source>

The server is expected to a) replace the conditional reference by the actual id of the one resource that matches the criteria b) return an error (412 - precondition failed) if no resource matches the criteria (..or rather: 404???) c) return an error (412 - precondition failed) if multiple resources matches the criteria

Other possible use cases are

  • Referencing an Insurance Organisation by the National Insurance Identifier
  • Referencing a Location by it's name
  • V2 mapping scenarios

Proposed Track Lead

Simone Heckmann

  • Email: simone dot heeckmann at health-comm dot de


See Connectathon_Track_Lead_Responsibilities

Expected participants

  • Simone Heckmann (Health-Comm): Client implementation (V2 Mapping Scenarios)

Roles

Client

Server

Scenarios

Scenario Step 1 Name

Action:
Precondition:
Success Criteria:
Bonus point:


TestScript(s)