International Patient Access
0.1.0 - STU 1 ballot

This page is part of the International Patient Access (v0.1.0: STU 1 Ballot 1) based on FHIR R4. . For a full list of available versions, see the Directory of published versions

: IPA Fetch DocumentReference - JSON Representation

Raw json | Download


{
  "resourceType" : "OperationDefinition",
  "id" : "docref",
  "text" : {
    "status" : "extensions",
    "div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><h2>IPAFetchDocumentReference</h2><p>OPERATION: IPAFetchDocumentReference</p><p>The official URL for this operation definition is: </p><pre>http://hl7.org/fhir/uv/ipa/OperationDefinition/docref</pre><div><p>This operation is used to return all the references to documents related to a patient.</p>\n<p>The operation requires a patient id and takes the optional input parameters:</p>\n<ul>\n<li>start date</li>\n<li>end date</li>\n<li>document type</li>\n</ul>\n<p>and returns a <a href=\"http://hl7.org/fhir/bundle.html\">Bundle</a> of type &quot;searchset&quot; containing <a href=\"StructureDefinition-ipa-documentreference.html\">DocumentReference</a> resources for the patient. If the server has or can create documents that are related to the patient, and that are available for the given user, the server returns the DocumentReference resources needed to support the records.  The principle intended use for this operation is to provide a patient with access to their available document information.</p>\n<p>This operation is <em>different</em> from a search by patient and type and date range because:</p>\n<ol>\n<li>\n<p>It is used to request a server <em>generate</em> a document based on the specified parameters.</p>\n</li>\n<li>\n<p>If no parameters are specified, the server SHALL return a DocumentReference to the patient's most current summary document (depending on jurisdiction)</p>\n</li>\n<li>\n<p>If the server cannot <em>generate</em> a document based on the specified parameters, the operation will return an empty search bundle.</p>\n</li>\n</ol>\n<p>This operation is the <em>same</em> as a FHIR RESTful search by patient, type and date range because:</p>\n<ol>\n<li>References for <em>existing</em> documents that meet the requirements of the request SHOULD also be returned unless the client indicates they are only interested in 'on-demand' documents using the <em>on-demand</em> parameter.</li>\n</ol>\n</div><p>Parameters</p><table class=\"grid\"><tr><td><b>Use</b></td><td><b>Name</b></td><td><b>Cardinality</b></td><td><b>Type</b></td><td><b>Binding</b></td><td><b>Documentation</b></td></tr><tr><td>IN</td><td>patient</td><td>1..1</td><td><a href=\"http://hl7.org/fhir/R4/datatypes.html#id\">id</a></td><td/><td><div><p>The id of the patient resource located on the server on which this operation is executed.  If there is no match, an empty Bundle is returned</p>\n</div></td></tr><tr><td>IN</td><td>start</td><td>0..1</td><td><a href=\"http://hl7.org/fhir/R4/datatypes.html#dateTime\">dateTime</a></td><td/><td><div><p>The date range relates to care dates, not record currency dates - e.g. all records relating to care provided in a certain date range. If no start date is provided, all documents prior to the end date are in scope.  If neither a start date nor an end date is provided, the most recent or current document is in scope.  The client <strong>SHOULD</strong> provide values precise to the second + time offset.</p>\n</div></td></tr><tr><td>IN</td><td>end</td><td>0..1</td><td><a href=\"http://hl7.org/fhir/R4/datatypes.html#dateTime\">dateTime</a></td><td/><td><div><p>The date range relates to care dates, not record currency dates - e.g. all records relating to care provided in a certain date range. If no end date is provided, all documents subsequent to the start date are in scope. If neither a start date nor an end date is provided, the most recent or current document is in scope.  The client <strong>SHOULD</strong> provide values precise to the second + time offset.</p>\n</div></td></tr><tr><td>IN</td><td>type</td><td>0..1</td><td><a href=\"http://hl7.org/fhir/R4/datatypes.html#CodeableConcept\">CodeableConcept</a></td><td><a href=\"http://hl7.org/fhir/R4/valueset-c80-doc-typecodes.html\">http://hl7.org/fhir/ValueSet/c80-doc-typecodes</a> (Example)</td><td><div><p>The type of document being requested. It relates to document type, e.g. the LOINC code for a C-CDA Continuity of Care Document (CCD) is 34133-9 (Summary of episode note). If no type is provided, a CDA document, if available, SHOULD be in scope and all other document types MAY be in scope</p>\n</div></td></tr><tr><td>IN</td><td>on-demand</td><td>0..1</td><td><a href=\"http://hl7.org/fhir/R4/datatypes.html#boolean\">boolean</a></td><td/><td><div><p>This on-demand parameter allows client to dictate whether they are requesting only ‘on-demand’ or both ‘on-demand’ and 'stable' documents (or delayed/deferred assembly) that meet the query parameters</p>\n</div></td></tr><tr><td>IN</td><td>pofile</td><td>0..1</td><td><a href=\"http://hl7.org/fhir/R4/datatypes.html#canonical\">canonical</a></td><td/><td><div><p>This parameter allows the client to request documents according to a specific profile, using the the profile's canonical reference</p>\n</div></td></tr><tr><td>OUT</td><td>return</td><td>1..1</td><td><a href=\"http://hl7.org/fhir/R4/bundle.html\">Bundle</a></td><td/><td><div><p>The bundle type is &quot;searchset&quot;containing <a href=\"http://hl7.org/fhir/documentreference.html\">DocumentReference</a> resources which <strong>SHOULD</strong> conform to the IPA <a href=\"StructureDefinition-ipa-documentreference.html\">profile of DocumentReference</a></p>\n</div></td></tr></table><div><ul>\n<li>\n<p>The server is responsible for determining what resources, if any, to return as <a href=\"http://hl7.org/fhir/R4/search.html#revinclude\">included</a> resources rather than the client specifying which ones. This frees the client from needing to determine what it could or should ask for. For example, the server may return the referenced document as an included FHIR Binary resource within the return bundle. The server's CapabilityStatement should document this behavior.</p>\n</li>\n<li>\n<p>The document itself can be subsequently retrieved using the link provided  in the <code>DocumentReference.content.attachment.url element</code>. The link could be a FHIR endpoint to a <a href=\"http://hl7.org/fhir/R4/binary.html\">Binary</a> Resource or some other document repository.</p>\n</li>\n<li>\n<p>It is assumed that the server has identified and secured the context appropriately, and can either associate the authorization context with a single patient, or determine whether the context has the rights to the nominated patient, if there is one. If there is no nominated patient (e.g. the operation is invoked at the system level) and the context is not associated with a single patient record, then the server should return an error. Specifying the relationship between the context, a user and patient records is outside the scope of this specification</p>\n</li>\n</ul>\n</div></div>"
  },
  "url" : "http://hl7.org/fhir/uv/ipa/OperationDefinition/docref",
  "version" : "0.1.0",
  "name" : "IPAFetchDocumentReference",
  "title" : "IPA Fetch DocumentReference",
  "status" : "draft",
  "kind" : "operation",
  "date" : "2021-10-05",
  "publisher" : "HL7 International - Patient Care Workgroup",
  "contact" : [
    {
      "telecom" : [
        {
          "system" : "url",
          "value" : "https://www.hl7.org/Special/committees/patientcare"
        }
      ]
    }
  ],
  "description" : "This operation is used to return all the references to documents related to a patient. \n\n The operation requires a patient id and takes the optional input parameters: \n  - start date\n  - end date\n  - document type \n\n and returns a [Bundle](http://hl7.org/fhir/bundle.html) of type \"searchset\" containing [DocumentReference](StructureDefinition-ipa-documentreference.html) resources for the patient. If the server has or can create documents that are related to the patient, and that are available for the given user, the server returns the DocumentReference resources needed to support the records.  The principle intended use for this operation is to provide a patient with access to their available document information. \n\n This operation is *different* from a search by patient and type and date range because: \n\n 1. It is used to request a server *generate* a document based on the specified parameters. \n\n 1. If no parameters are specified, the server SHALL return a DocumentReference to the patient's most current summary document (depending on jurisdiction) \n\n 1. If the server cannot *generate* a document based on the specified parameters, the operation will return an empty search bundle. \n\n This operation is the *same* as a FHIR RESTful search by patient, type and date range because: \n\n 1. References for *existing* documents that meet the requirements of the request SHOULD also be returned unless the client indicates they are only interested in 'on-demand' documents using the *on-demand* parameter.",
  "jurisdiction" : [
    {
      "coding" : [
        {
          "system" : "http://unstats.un.org/unsd/methods/m49/m49.htm",
          "code" : "001"
        }
      ]
    }
  ],
  "code" : "docref",
  "comment" : " - The server is responsible for determining what resources, if any, to return as [included](http://hl7.org/fhir/R4/search.html#revinclude) resources rather than the client specifying which ones. This frees the client from needing to determine what it could or should ask for. For example, the server may return the referenced document as an included FHIR Binary resource within the return bundle. The server's CapabilityStatement should document this behavior. \n\n - The document itself can be subsequently retrieved using the link provided  in the `DocumentReference.content.attachment.url element`. The link could be a FHIR endpoint to a [Binary](http://hl7.org/fhir/R4/binary.html) Resource or some other document repository. \n\n - It is assumed that the server has identified and secured the context appropriately, and can either associate the authorization context with a single patient, or determine whether the context has the rights to the nominated patient, if there is one. If there is no nominated patient (e.g. the operation is invoked at the system level) and the context is not associated with a single patient record, then the server should return an error. Specifying the relationship between the context, a user and patient records is outside the scope of this specification",
  "system" : false,
  "type" : true,
  "instance" : false,
  "parameter" : [
    {
      "name" : "patient",
      "use" : "in",
      "min" : 1,
      "max" : "1",
      "documentation" : "The id of the patient resource located on the server on which this operation is executed.  If there is no match, an empty Bundle is returned",
      "type" : "id"
    },
    {
      "name" : "start",
      "use" : "in",
      "min" : 0,
      "max" : "1",
      "documentation" : "The date range relates to care dates, not record currency dates - e.g. all records relating to care provided in a certain date range. If no start date is provided, all documents prior to the end date are in scope.  If neither a start date nor an end date is provided, the most recent or current document is in scope.  The client **SHOULD** provide values precise to the second + time offset.",
      "type" : "dateTime"
    },
    {
      "name" : "end",
      "use" : "in",
      "min" : 0,
      "max" : "1",
      "documentation" : "The date range relates to care dates, not record currency dates - e.g. all records relating to care provided in a certain date range. If no end date is provided, all documents subsequent to the start date are in scope. If neither a start date nor an end date is provided, the most recent or current document is in scope.  The client **SHOULD** provide values precise to the second + time offset.",
      "type" : "dateTime"
    },
    {
      "name" : "type",
      "use" : "in",
      "min" : 0,
      "max" : "1",
      "documentation" : "The type of document being requested. It relates to document type, e.g. the LOINC code for a C-CDA Continuity of Care Document (CCD) is 34133-9 (Summary of episode note). If no type is provided, a CDA document, if available, SHOULD be in scope and all other document types MAY be in scope",
      "type" : "CodeableConcept",
      "binding" : {
        "strength" : "example",
        "valueSet" : "http://hl7.org/fhir/ValueSet/c80-doc-typecodes"
      }
    },
    {
      "name" : "on-demand",
      "use" : "in",
      "min" : 0,
      "max" : "1",
      "documentation" : "This on-demand parameter allows client to dictate whether they are requesting only ‘on-demand’ or both ‘on-demand’ and 'stable' documents (or delayed/deferred assembly) that meet the query parameters",
      "type" : "boolean"
    },
    {
      "name" : "pofile",
      "use" : "in",
      "min" : 0,
      "max" : "1",
      "documentation" : "This parameter allows the client to request documents according to a specific profile, using the the profile's canonical reference",
      "type" : "canonical"
    },
    {
      "name" : "return",
      "use" : "out",
      "min" : 1,
      "max" : "1",
      "documentation" : "The bundle type is \"searchset\"containing [DocumentReference](http://hl7.org/fhir/documentreference.html) resources which **SHOULD** conform to the IPA [profile of DocumentReference](StructureDefinition-ipa-documentreference.html)",
      "type" : "Bundle"
    }
  ]
}