This wiki has undergone a migration to Confluence found Here

Difference between revisions of "201605 Conditional Reference Connectathon Proposal"

From HL7Wiki
Jump to navigation Jump to search
 
(14 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
+
[http://wiki.hl7.org/index.php?title=Category:201605_FHIR_Connectathon_Track_Proposals Return to May 2016 Proposals]
 
[[Category:201605_FHIR_Connectathon_Track_Proposals|May 2016 Proposals]]
 
[[Category:201605_FHIR_Connectathon_Track_Proposals|May 2016 Proposals]]
 
__NOTOC__
 
__NOTOC__
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 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.
+
(e.g. where national identifiers are used). However since FHIR resources 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 retrieve 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.
+
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 intends to read only. 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.
 
Example: The Client wants to create an Observation linked to the Patient with business identifier 12345.
Line 22: Line 22:
  
 
   <Bundle xmlns="http://hl7.org/fhir">
 
   <Bundle xmlns="http://hl7.org/fhir">
  <id value="20160113160203" />
+
    <id value="20160113160203" />
  <type value="transaction" />
+
    <type value="transaction" />
  <entry>
+
    <entry>
  <fullUrl value="urn:uuid:653a9d22-b6c1-44cd-55a0-3ce35d574642" />
+
      <fullUrl value="urn:uuid:653a9d22-b6c1-44cd-55a0-3ce35d574642" />
  <resource>
+
      <resource>
  <Patient>
+
        <Patient>
  <identifier>
+
          <identifier>
  <value value="12345" />
+
            <value value="12345" />
  </identifier>
+
          </identifier>
  </Patient>
+
        </Patient>
  </resource>
+
      </resource>
  <request>
+
      <request>
  <method value="CREATE" />
+
        <method value="POST" />
  <if-none-exixts="Patient?identifier=12345" />
+
        <if-none-exixts="Patient?identifier=12345" />
  </request>
+
      </request>
  </entry>
+
    </entry>
  <entry>
+
    <entry>
  <fullUrl value="urn:uuid:c72aa430-2ddc-456e-7a09-dea8264671d8" />
+
      <fullUrl value="urn:uuid:c72aa430-2ddc-456e-7a09-dea8264671d8" />
  <resource>
+
      <resource>
  <Observation>
+
        <Observation>
                <subject>
+
          <subject>
                                  <reference value="urn:uuid:653a9d22-b6c1-44cd-55a0-3ce35d574642"/>
+
            <reference value="urn:uuid:653a9d22-b6c1-44cd-55a0-3ce35d574642"/>
                          </subject>
+
          </subject>
                        </Observation>
+
          <--! rest of resource omitted -->
            </resource>
+
        </Observation>
            <request>
+
      </resource>
                  <method value="CREATE" />
+
      <request>
            </request>
+
        <method value="POST" />
        </entry>
+
      </request>
 +
    </entry>
 
   </Bundle>
 
   </Bundle>
 
 
Line 57: Line 58:
 
* no patient matches the create condition and the subsequent create action runs into an error due to insufficient client permissions
 
* no patient matches the create condition and the subsequent create action runs into an error due to insufficient client permissions
 
* multiple patients match the create condition
 
* multiple patients match the create condition
The proposal has been made to allow conditional references with the same syntax as conditional updates.
 
  
  
Line 63: Line 63:
 
<source lang="xml">
 
<source lang="xml">
 
   <Bundle xmlns="http://hl7.org/fhir">
 
   <Bundle xmlns="http://hl7.org/fhir">
  <id value="20160113160203" />
+
    <id value="20160113160203" />
  <type value="transaction" />
+
    <type value="transaction" />
  <entry>
+
    <entry>
  <fullUrl value="urn:uuid:c72aa430-2ddc-456e-7a09-dea8264671d8" />
+
      <fullUrl value="urn:uuid:c72aa430-2ddc-456e-7a09-dea8264671d8" />
  <resource>
+
      <resource>
  <Observation>
+
        <Observation>
              <subject>
+
          <subject>
                                  <reference value="Patient?identifier=12345"/>
+
            <reference value="Patient?identifier=12345"/>
                          </subject>
+
          </subject>
                        </Observation>
+
          <--! rest of resource omitted -->
          </resource>
+
        </Observation>
            <request>
+
      </resource>
                <method value="CREATE" />
+
      <request>
            </request>
+
        <method value="POST" />
        </entry>
+
      </request>
 +
    </entry>
 
   <Bundle>
 
   <Bundle>
 
</source>
 
</source>
Line 91: Line 92:
  
 
Simone Heckmann
 
Simone Heckmann
* Email: simone dot heeckmann at health-comm dot de
+
* Email: simone dot heckmann at health-comm dot de
  
  
Line 99: Line 100:
  
 
* Simone Heckmann (Health-Comm): Client implementation (V2 Mapping Scenarios)
 
* Simone Heckmann (Health-Comm): Client implementation (V2 Mapping Scenarios)
 +
* James Agnew (HAPI): Server implementation
  
 
==Roles==
 
==Roles==
  
 
===Client===
 
===Client===
The Client sumbits Bundles to the server including conditional references as proposed above.
+
The Client submits Bundles to the server including conditional references as proposed above.
  
 
===Server===
 
===Server===
Line 111: Line 113:
 
The server is expected to
 
The server is expected to
 
* replace the conditional reference by the actual id of the one resource that matches the criteria  
 
* replace the conditional reference by the actual id of the one resource that matches the criteria  
* return an HTTP 500 if no resource matches the criteria  
+
* return an HTTP 404 if no resource matches the criteria  
* return an HTTP 500 if multiple resources matches the criteria
+
* return an HTTP 412 if multiple resources matches the criteria
  
 
==Scenarios==
 
==Scenarios==
 
<!-- What will be the actions performed by participants? -->
 
<!-- What will be the actions performed by participants? -->
 +
The mechanisms described above can be used in any scenario that leverages FHIR Transactions, e.g. any of the [http://wiki.hl7.org/index.php?title=Version_2_-_FHIR_Mapping_Scenarios FHIR-V2-Mapping Scenarios]
  
 
===Scenario Step 1 Conditional URL matches one resource===
 
===Scenario Step 1 Conditional URL matches one resource===
Line 121: Line 124:
 
:Precondition: Client has to make sure it references an existing Resource uniquely identified by the query criteria  
 
:Precondition: Client has to make sure it references an existing Resource uniquely identified by the query criteria  
 
:Success Criteria: Server returns HTTP 200 with transaction resonse bundle. Visual inspection of the resource on the server to confirm that the reference has been updated properly
 
:Success Criteria: Server returns HTTP 200 with transaction resonse bundle. Visual inspection of the resource on the server to confirm that the reference has been updated properly
:Bonus point: Client automatically checks the correct resolution of the reference by sending a query that confirms the success (Example for the Bundle above: Observation?subject.identifier=12345 should return the subitted Observation
+
:Bonus point: Client automatically checks the correct resolution of the reference by sending a query that confirms the success (Example for the Bundle above: Observation?subject.identifier=12345 should return the submitted Observation
  
 
===Scenario Step 2 Conditional URL matches multiple resources===
 
===Scenario Step 2 Conditional URL matches multiple resources===
 
:Action: Client submits Transaction Bundle with at least one Resource containing a conditional reference that matches multiple  Resources on the Server
 
:Action: Client submits Transaction Bundle with at least one Resource containing a conditional reference that matches multiple  Resources on the Server
 
:Precondition: Client has to make sure it uses query criteria that returns more than one match
 
:Precondition: Client has to make sure it uses query criteria that returns more than one match
:Success Criteria: Server returns HTTP 500, no update is performed
+
:Success Criteria: Server returns HTTP 412, no update is performed
 
:Bonus point: Server returns Operation Outcome with verbose information about the issue
 
:Bonus point: Server returns Operation Outcome with verbose information about the issue
  
Line 132: Line 135:
 
:Action: Client submits Transaction Bundle with at least one Resource containing a conditional reference that matches no Resources on the Server
 
:Action: Client submits Transaction Bundle with at least one Resource containing a conditional reference that matches no Resources on the Server
 
:Precondition: Client has to make sure it uses query criteria that returns no match
 
:Precondition: Client has to make sure it uses query criteria that returns no match
:Success Criteria: Server returns HTTP 500, no update is performed
+
:Success Criteria: Server returns HTTP 404, no update is performed
 
:Bonus point: Server returns Operation Outcome with verbose information about the issue
 
:Bonus point: Server returns Operation Outcome with verbose information about the issue
  
Line 139: Line 142:
 
These should be committed to SVN under trunk/connectathons/[connectathon]
 
These should be committed to SVN under trunk/connectathons/[connectathon]
 
-->
 
-->
 +
The supporting TestScripts and corresponding fixtures have been committed to the FHIR SVN repository at:
 +
http://gforge.hl7.org/svn/fhir/trunk/connectathons/MontrealMay2016/Connectathon12/Track-04-ConditionRef
 +
 +
===TestScript Definitions===
 +
The TestScript resources** in this folder are examples of an Encounter resource create via a transaction operation where the Patient and Organization references are defined using conditional parameters.
 +
 +
''**The Track 04 - Conditional Reference tests are not meant to be definitive and complete. This is one example of how these tests can be defined in the current STU 3 Candidate format of the TestScript resource. Constructive feedback, suggestions and criticisms are welcome.''
 +
 +
The following TestScript definitions are currently available:
 +
 +
====Encounter Conditional Reference - JSON====
 +
* '''connectathon-12-track-04-condref-encounter-match-json''' -- JSON Format - Test conditional reference transaction update of an Encounter resource. Referenced Patient and Organization resources are first created on the destination server.
 +
* '''connectathon-12-track-04-condref-encounter-multimatch-json''' -- JSON Format - Test conditional reference transaction create of an Encounter resource. Referenced Patient and Organization resources are first created on the destination server. Multiple matching Patient resources are expected to cause the Encounter create to fail.
 +
* '''connectathon-12-track-04-condref-encounter-nomatch-json''' -- JSON Format - Test conditional reference transaction create of an Encounter resource. Referenced Organization resource is first created on the destination server. No matching Patient resources are expected to cause the Encounter create to fail.
 +
 +
====Encounter Conditional Reference - XML====
 +
* '''connectathon-12-track-04-condref-encounter-match-xml''' -- XML Format - Test conditional reference transaction update of an Encounter resource. Referenced Patient and Organization resources are first created on the destination server.
 +
* '''connectathon-12-track-04-condref-encounter-multimatch-xml''' -- XML Format - Test conditional reference transaction create of an Encounter resource. Referenced Patient and Organization resources are first created on the destination server. Multiple matching Patient resources are expected to cause the Encounter create to fail.
 +
* '''connectathon-12-track-04-condref-encounter-nomatch-xml''' -- XML Format - Test conditional reference transaction create of an Encounter resource. Referenced Organization resource is first created on the destination server. No matching Patient resources are expected to cause the Encounter create to fail.
 +
 +
===Conventions Used===
 +
The execution of the TestScript resources contained in this folder are constrained by the following conventions:
 +
 +
'''Fixtures''' - All resource reference values can be either url paths or local local file system paths. The convention for these TestScript resources use local file system paths where the execution engine is expected to resolve this path based on the following:
 +
* Leading '/' character - this is resolved as an absolute path based on a known root path.
 +
* No leading '/' character - this is resolved as a relative path based on the location of the TestScript resource file.

Latest revision as of 13:18, 8 May 2016

Return to May 2016 Proposals

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. where national identifiers are used). However since FHIR resources 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 retrieve 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 intends to read only. 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

  1. search for a patient that matches the condition
  2. 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="POST" />
       <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>
         <--! rest of resource omitted -->
       </Observation>
      </resource>
     <request>
       <method value="POST" />
     </request>
   </entry>
 </Bundle>


The transcaction would fail if

  • no patient matches the create condition and the subsequent create action runs into an error due to insufficient client permissions
  • multiple patients match the create condition


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>
         <--! rest of resource omitted -->
       </Observation>
     </resource>
     <request>
       <method value="POST" />
     </request>
   </entry>
 <Bundle>

</source>


Other possible use cases are

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

Proposed Track Lead

Simone Heckmann

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


See Connectathon_Track_Lead_Responsibilities

Expected participants

  • Simone Heckmann (Health-Comm): Client implementation (V2 Mapping Scenarios)
  • James Agnew (HAPI): Server implementation

Roles

Client

The Client submits Bundles to the server including conditional references as proposed above.

Server

The Server receives the Bundles and processes them as described above

The server is expected to

  • replace the conditional reference by the actual id of the one resource that matches the criteria
  • return an HTTP 404 if no resource matches the criteria
  • return an HTTP 412 if multiple resources matches the criteria

Scenarios

The mechanisms described above can be used in any scenario that leverages FHIR Transactions, e.g. any of the FHIR-V2-Mapping Scenarios

Scenario Step 1 Conditional URL matches one resource

Action: Client submits Transaction Bundle with at least one Resource containing a conditional reference that matches exactly one Resource on the Server
Precondition: Client has to make sure it references an existing Resource uniquely identified by the query criteria
Success Criteria: Server returns HTTP 200 with transaction resonse bundle. Visual inspection of the resource on the server to confirm that the reference has been updated properly
Bonus point: Client automatically checks the correct resolution of the reference by sending a query that confirms the success (Example for the Bundle above: Observation?subject.identifier=12345 should return the submitted Observation

Scenario Step 2 Conditional URL matches multiple resources

Action: Client submits Transaction Bundle with at least one Resource containing a conditional reference that matches multiple Resources on the Server
Precondition: Client has to make sure it uses query criteria that returns more than one match
Success Criteria: Server returns HTTP 412, no update is performed
Bonus point: Server returns Operation Outcome with verbose information about the issue

Scenario Step 3 Conditional URL matches no resource

Action: Client submits Transaction Bundle with at least one Resource containing a conditional reference that matches no Resources on the Server
Precondition: Client has to make sure it uses query criteria that returns no match
Success Criteria: Server returns HTTP 404, no update is performed
Bonus point: Server returns Operation Outcome with verbose information about the issue

TestScript(s)

The supporting TestScripts and corresponding fixtures have been committed to the FHIR SVN repository at: http://gforge.hl7.org/svn/fhir/trunk/connectathons/MontrealMay2016/Connectathon12/Track-04-ConditionRef

TestScript Definitions

The TestScript resources** in this folder are examples of an Encounter resource create via a transaction operation where the Patient and Organization references are defined using conditional parameters.

**The Track 04 - Conditional Reference tests are not meant to be definitive and complete. This is one example of how these tests can be defined in the current STU 3 Candidate format of the TestScript resource. Constructive feedback, suggestions and criticisms are welcome.

The following TestScript definitions are currently available:

Encounter Conditional Reference - JSON

  • connectathon-12-track-04-condref-encounter-match-json -- JSON Format - Test conditional reference transaction update of an Encounter resource. Referenced Patient and Organization resources are first created on the destination server.
  • connectathon-12-track-04-condref-encounter-multimatch-json -- JSON Format - Test conditional reference transaction create of an Encounter resource. Referenced Patient and Organization resources are first created on the destination server. Multiple matching Patient resources are expected to cause the Encounter create to fail.
  • connectathon-12-track-04-condref-encounter-nomatch-json -- JSON Format - Test conditional reference transaction create of an Encounter resource. Referenced Organization resource is first created on the destination server. No matching Patient resources are expected to cause the Encounter create to fail.

Encounter Conditional Reference - XML

  • connectathon-12-track-04-condref-encounter-match-xml -- XML Format - Test conditional reference transaction update of an Encounter resource. Referenced Patient and Organization resources are first created on the destination server.
  • connectathon-12-track-04-condref-encounter-multimatch-xml -- XML Format - Test conditional reference transaction create of an Encounter resource. Referenced Patient and Organization resources are first created on the destination server. Multiple matching Patient resources are expected to cause the Encounter create to fail.
  • connectathon-12-track-04-condref-encounter-nomatch-xml -- XML Format - Test conditional reference transaction create of an Encounter resource. Referenced Organization resource is first created on the destination server. No matching Patient resources are expected to cause the Encounter create to fail.

Conventions Used

The execution of the TestScript resources contained in this folder are constrained by the following conventions:

Fixtures - All resource reference values can be either url paths or local local file system paths. The convention for these TestScript resources use local file system paths where the execution engine is expected to resolve this path based on the following:

  • Leading '/' character - this is resolved as an absolute path based on a known root path.
  • No leading '/' character - this is resolved as a relative path based on the location of the TestScript resource file.