HL7中国FHIR Connectathon测试实施指南
2024.5.5 - release

本指南适用于HL7中国的FHIR Connectathon测试。

文档共享服务规范

概述

文档共享服务（XDS-on-FHIR）交互规范定义了一个基于FHIR规范的共享文档交互接口。

在交互规范中定义的交易参考了IHE的XDS、MHD、NPFS规范。

本交互规范寻求一种IHE XDS的替代方案，简化交互接口，适用于当前流行的网络交互。

基于FHIR R5版本进行设计。

与XDS规范的对应：

  XDS FHIR
提交集 SubmissionSet List
文档条目 DocumentEntry DocumentReference
文档 XDS Document Binary

关联关系：

  • 提交集与文档条目的关联关系记录在List资源的entry元素中。
  • 文档条目与文档的关联关系记录在DocumentReference资源的content.attachment.url元素中。

不足

  • 文档在传输过程中进行了Base64编码，增加了1/3的体积。

用例场景

用例图

角色

  • 文档源：文档源是文档的生产者和发布者。
  • 文档存储库：文档存储库维护着上传的文档。
  • 文档注册库：文档注册库维护者文档的元数据和提交集元数据。
  • 文档消费者：文档消费者向文档注册库查询满足特定条件的文档元数据，并可以获取选定的文档。

用例

用例1:

在2020年10月28日，社区医生赵勇对慢病患者张三进行糖尿病随访时，使用移动设备上的随访应用对随访信息进行了记录。在完成随访后，形成慢病随访记录文档。点击提交文档，将文档与元数据一起提交到社区中心。

在此用例中，移动设备上的随访应用实现了文档源角色，可以提交一份或一组文档到文档存储库。

用例2:

社区医生赵勇想查看一下他负责的慢病患者张三在本月内的随访记录，在移动设备上的随访应用中输入过滤条件患者姓名=张三、起止时间为本月的1-31日，点击查询按钮，界面中显示本月一共对患者张三进行了2次随访。社区医生赵勇想查看一下患者张三的最后一次随访记录，在查询结果页面，点击最后的那一次随访记录，界面显示了该次随访记录的详细信息。

在此用例中，移动设备上的随访应用实现了文档使用者角色，可以向文档注册库发起文档查询请求。还实现了文档使用者角色，可以从文档存储库获取一份指定的文档。

交易

在本交互规范的当前版本定义了如下3个交易：

提交文档集(IST-FHIR-XDS-001)

本交易由文档源和文档存储库角色使用。提交文档集(IST-FHIR-XDS-001)交易用于传输一组文档和相关元数据。

调用地址:

POST http://[ip]:[port]/fhir/[docrepo]
请求消息

此消息使用POST方法将元数据和文档作为Bundle资源进行传输。

请求消息体的Content-Type必须为application/fhir+json 或者 application/fhir+xml。

消息体定义和示例参见ProvideDocumentBundle：

  • Bundle资源的元素type=transaction
  • 应含有唯一一个List资源
  • 应含有一到多个DocumentReference资源
  • 应含有零到多个Binary资源
  • 所有DocumentReference资源、List资源必须都指向同一个患者资源，患者资源的标识的获取不在本规范的涵盖范围内。
  • 应验证文档的Hash值
响应消息

响应消息处理可参见FHIR规范的事务处理。

响应消息体的定义参见ProvideDocumentBundleResponse：

  • 处理成功：
    • Bundle资源的元素type=transaction-response
    • 使用状态码200 OK标识整个请求处理成功
    • Bundle.entry.response.status标记为201 Created，表示资源创建成功
  • 处理失败：
    • 使用状态码400和500标识整个请求处理失败
    • 使用单个的OperationOutcome来代替Bundle

查询文档(IST-FHIR-XDS-002)

本交易由文档消费者和文档注册库角色使用。查询文档(IST-FHIR-XDS-002)交易用于查找满足一组参数的DocumentReference资源。

查询的结果是一个FHIR包，其中包含与查询参数匹配的DocumentReference资源。

调用地址:

POST http://[ip]:[port]/api/[docreg]/DocumentReference?<query param>
请求消息

查询参数表示为一系列的name-value对，这些name-value对表示查询的筛选器，在本规范的当前版本中需支持：

参数 参数类型 描述 对应元素
category token 表示文档的分类（粗粒度分类） category
type token 表示文档的类型（细粒度分类） type
date date 文档的创建时间 date
identifier token 文档的唯一标识（UniqueId） identifier
patient reference 标识文档记录的就诊事件中的患者 subject
patient.identifier token 标识文档记录的就诊事件中的患者。链式查询 subject
patient.name string 患者的姓名。链式查询 subject
author reference 文档作者（责任医师） author
author.name string 文档作者（责任医师）的姓名。链式查询 author
custodian reference 文档保管机构 custodian
custodian.name string 文档保管机构的名称 custodian
period date 标识文档记录的就诊事件的起止时间 context.period
relatesto reference 关联的文档 relatesTo.target
relation token 与关联的文档的关系 relatesTo.code
status token 文档的状态 status
响应消息

响应消息返回恰当的HTTP状态代码以及Bundle资源，其中包含匹配查询条件的DocumentReference资源。

响应消息体的定义参见FindDocumentReferenceResponse：

  • 如果执行成功，返回200 OK状态码，且Bundle资源中应包含有零到多个DocumentReference资源。
  • 如果执行失败，则应返回OperationOutcome资源。具体内容参见后面的“异常处理”章节。
示例
  • 请求消息
GET /repository/api/DocumentReference?type=http:%2F%2Floinc.org%7C51847-2 HTTP/1.1
Host: fhirserver.com
  • 响应消息
HTTP/1.1 200 OK
Server: nginx/1.18.0 (Ubuntu)
Date: Fri, 14 May 2021 05:29:09 GMT
Content-Type: application/fhir+json;charset=utf-8
Transfer-Encoding: chunked
Connection: close
X-Powered-By: HAPI FHIR 5.4.0 REST Server (FHIR Server; FHIR 5.0.0/R5)
Last-Modified: Fri, 14 May 2021 05:29:09 GMT

{
  "resourceType": "Bundle",
  "id": "cc2bcb8f-12ed-4178-bb0b-80c614a47f49",
  "meta": {
    "lastUpdated": "2021-05-14T05:29:09.648+00:00"
  },
  "type": "searchset",
  "link": [ {
    "relation": "self",
    "url": "http://fhirserver.com/repository/api/DocumentReference?type=http%3A%2F%2Floinc.org%7C51847-2"
  }, {
    "relation": "next",
    "url": "http://fhirserver.com/repository/api?_getpages=cc2bcb8f-12ed-4178-bb0b-80c614a47f49&_getpagesoffset=20"
  } ],
  "entry": [ {
    "fullUrl": "http://fhirserver.com/repository/api/DocumentReference/1963433",
    "resource": {
      "resourceType": "DocumentReference",
      "id": "1963433",
      "meta": {
        "versionId": "1",
        "lastUpdated": "2021-03-22T17:55:21.282+00:00",
        "source": "#BNMOOv5FotI8XAw5"
      },
      "status": "superseded",
      "type": {
        "coding": [ {
          "system": "http://loinc.org",
          "code": "51847-2",
          "display": "Evaluation+Plan note"
        } ]
      },
      "category": [ {
        "coding": [ {
          "system": "http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category",
          "code": "clinical-note",
          "display": "Clinical Note"
        } ]
      } ],
      "subject": {
        "reference": "Patient/5af4663e-8b67-47fc-9cf4-d85292360a64"
      },
      "date": "2002-08-19T16:45:50.597-05:00",
      "author": [ {
        "reference": "Practitioner/0000016f-a1db-e77f-0000-0000000404de",
      } ],
      "content": [ {
        "attachment": {
          "contentType": "text/plain",
          "data": "EoyWVhScGRtVWdabkpsWlM0Z0NnPT0="
        }
      } ],
      "context": {
        "period": {
          "start": "2002-08-19T16:45:50-05:00",
          "end": "2002-08-19T17:00:50-05:00"
        }
      }
    },
    "search": {
      "mode": "match"
    }
  }, 
  ...
  ]
}

获取文档(IST-FHIR-XDS-003)

本交易由文档消费者和文档存储库角色使用。获取文档(IST-FHIR-XDS-003)交易用于根据指定的文档标识获取文档内容。

调用地址:

POST http://[ip]:[port]/[docrepo]/api/Binary/[id]
请求消息

此消息使用GET方法根据文档的标识符获取指定文档的原始数据内容。

  • 唯一需要的参数就是文档的id
响应消息

响应消息是文档的原始数据。注意！不是Base64编码后的数据。

示例
  • 请求消息
GET /repository/api/Binary/2073919 HTTP/1.1
Host: fhirserver.com
  • 响应消息
HTTP/1.1 200 OK
Server: nginx/1.18.0 (Ubuntu)
Date: Wed, 12 May 2021 08:57:57 GMT
Content-Type: text/xml
Content-Length: 123456
Connection: close
X-Powered-By: HAPI FHIR 5.4.0 REST Server (FHIR Server; FHIR 5.0.0/R5)
ETag: W/"1"
Content-Location: http://fhirserver.com/repository/api/Binary/2073919/_history/1
Content-Disposition: Attachment;

<?xml version="1.0" encoding="UTF-8"?>
<ClinicalDocument xmlns="urn:hl7-org:v3" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" classCode="DOCCLIN" moodCode="EVN">
  <realmCode code="CN"/>
  <typeId root="2.16.840.1.113883.1.3" extension="POCD_MT000040"/>
  <templateId root="2.16.156.10011.2.1.1.1.1"/>
  <id root="2.16.156.10011.1.1.1.2" extension="20110211336666666"/>
  <code code="HSDA00.01" displayName="个人基本健康信息登记" codeSystem="2.16.156.10011.2.4" codeSystemName="卫生信息共享文档规范编码体系"/>
  <title>个人基本健康信息登记</title>
  <effectiveTime value="20151114003556"/>
  <confidentialityCode code="N" displayName="正常访问保密级别" codeSystem="2.16.840.1.113883.5.25" codeSystemName="Confidentiality"/>
  <languageCode code="zh-CN"/>
  
  ...

</ClinicalDocument>

异常处理

文档存储异常错误定义

文档存储异常消息定义和示例参见XDSRepOperationOutcome。

当处理流程出现错误时：

  • 使用状态码4xx和5xx标识整个请求处理失败
  • 响应消息体使用OperationOutcome资源代替Bundle资源。
  • 下表给出了details的取值：
代码 说明
XDSRepositoryMetadataError 元数据错误
XDSMissingDocument 文档元数据指向的文档未找到
XDSRepositoryDuplicateUniqueIdInMessage 在同一消息中发现同样的UniqueId
XDSNonIdenticalHash 文档id一样，但Hash值不一样
XDSNonIdenticalSize 文档id一样，但Size值不一样
XDSRegistryNotAvailable 文档注册服务不可访问
XDSRepositoryError 其它的文档存储错误

文档注册异常错误定义

文档注册异常消息定义和示例参见XDSRegOperationOutcome。

当处理流程出现错误时：

  • 使用状态码4xx和5xx标识整个请求处理失败
  • 响应消息体使用OperationOutcome资源代替Bundle资源。
  • 下表给出了details的取值：
代码 说明
XDSRegistryMetadataError 元数据错误
XDSPatientIdDoesNotMatch 患者标识不匹配
XDSDuplicateUniqueIdInRegistry 在注册库唯一标识重复。例如文档id与提交集标识重复
XDSNonIdenticalHash 文档id一样，但Hash值不一样
XDSNonIdenticalSize 文档id一样，但Size值不一样
XDSUnknownPatientId 无法识别的患者标识
XDSDocumentUniqueIdError 文档唯一标识错误。因多种原因通过该标识无法获取到文档，例如：无权访问，文档已失效
XDSRegistryError 其它的文档注册错误