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

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

CDS-Hooks服务规范

概述

适用于临床信息系统与临床辅助决策系统的集成交互场景。

CDS Hooks:本测试用例要求基于CDS Hooks官方2019-04-23发布的STU release(v1.0)版本实现。https://cds-hooks.hl7.org/1.0/

测试仅覆盖CDS Hooks相关的核心资源(Patient,Encounter、Observation、MedicationRequest等),不涉及相关流程和扩展资源,引用的相应FHIR资源不进行扩展性验证。

测试采用基于HTTP协议的RESTful API方式,现场点对点联接客户端和服务器端测试。

用例场景

CDS Hooks 规范描述了 RESTful API 和交互,用于在 CDS 客户端(通常是电子病历系统 (EMR) 或其他医疗健康信息系统)和 CDS 服务之间集成临床决策支持系统(CDS),以下分别用“CDS客户端”和“CDS服务端”指代两个角色。

说明:考虑到测试的可操作性,忽略相关的鉴权认证流程。

参与角色

  • 客户端:CDS客户端,能触发CDS Hooks,调用CDS服务,并显示FHIR资源和用户交互
  • 服务器:CDS服务端,提供CDS服务,封装、解析、存储FHIR资源

用例

用例1:

CDS客户端向CDS服务端获取服务列表,CDS服务端返回支持的服务资源,CDS客户端显示或者配置相关服务参数。

用例2:

CDS客户端触发显示患者信息事件,CDS客户端向CDS服务端调用患者信息展示服务,CDS服务端返回患者资源,CDS客户端显示患者相关信息。

用例3:

CDS客户端触发显示医嘱选择事件,CDS客户端向CDS服务端调用医嘱选择服务,CDS服务端返回推荐医嘱资源,CDS客户端显示推荐医嘱相关信息。

交易

在本交互规范中定义了如下3个交易:

CDS服务发现交易

本交易由CDS客户端和CDS服务端使用。 调用地址:

GET https://example.com/cds-services
请求消息

CDS服务描述应该始终在{baseUrl}/cds-services可以访问。

响应消息

返回一组services对象组成的数组。

每一个CDS服务应该包含下列属性。

字段 可选性 类型 描述
hook R string 应该调用此服务的钩子。
title C string 此服务的人性化名称。
description R string 此服务的描述。
id R string 此服务的 URL 的 {id} 部分可在{baseUrl}/cds-services/{id}
prefetch O object 包含此服务请求 CDS 客户端预取并在每次服务调用时提供的 FHIR 查询键/值对的对象。 键是描述所请求数据类型的字符串,值是表示 FHIR 查询的字符串。

响应消息返回恰当的HTTP状态代码。

  • 如果执行成功,返回200 OK状态码。
  • 如果执行失败,则应返回4xx和5xx HTTP错误代码。
示例
  • 请求消息
GET /cds-services HTTP/1.1
Host: fhir-org-cds-services.appspot.com
  • 响应消息
 {
    "services": [
        {
            "id": "cms-price-check",
            "title": "CMS Pricing Service",
            "description": "Determine if an authored prescription has a cheaper alternative to switch to and display pricing",
            "hook": "order-select"
        },
        {
            "id": "pama-imaging",
            "title": "Pama Imaging Connectathon 2019 Scenarios",
            "description": "Produce an appropriateness score according to scenario inputs.",
            "hook": "order-select"
        },
        {
            "id": "patient-greeting",
            "title": "Patient greeting",
            "description": "Display which patient the user is currently working with",
            "hook": "patient-view",
            "prefetch": {
                "patient": "Patient/"
            }
        }
    ]
}

CDS获取患者信息

本交易由CDS客户端和CDS服务端使用。 调用地址:

POST {baseUrl}/cds-services/{service.id}
请求消息

CDS客户端使用POST方法将描述服务的JSON文档传输至CDS服务端。

请求服务JSON文档包含的字段属性如下:

字段 可选性 类型 描述
hook R string 触发此 CDS 服务调用的钩子。
hookInstance R string 此特定钩子调用的UUID
fhirServer O URL CDS客户端的FHIR服务器的基本URL。 如果提供了fhirAuthorization,则此字段是必需的。 该方案应该是 https
fhirAuthorization O object 持有OAuth 2.0不记名访问令牌的结构,授予CDS服务访问FHIR资源的权限,以及与令牌相关的补充信息。
context R string CDS 服务将需要的特定于钩子的上下文数据。
例如,使用患者展示钩子,这将包括正在查看的患者的FHIR标识符。      
prefetch O object CDS 客户端预取的 FHIR 数据。

CDS客户端触发调用获取患者信息服务时context属性如下:

字段 可选性 预取令牌 类型 描述
userId R Y string 当前用户的id。例如,如果用户代表给定 FHIR 服务器上的 FHIR 资源,则资源类型将为 Practitioner、Patient 或 RelatedPerson 之一。
patientId R Y string 上下文中当前患者的 FHIR Patient.id。
encounterId O Y string 上下文中当前就诊的 FHIR Encounter.id
响应消息

返回一组cards对象组成的数组。 每一个Card应该包含下列属性。

字段 可选性 类型 描述
uuid 可选 string 卡的唯一标识符。可用于审核和记录卡,并应包含在对 CDS 服务的反馈端点的任何后续调用中。
summary 必须 string 一个句子,少于140个字符的摘要消息,用于在此卡片内向用户显示。
detail 可选 string 可选的详细信息显示;如果提供,则必须以(GitHub 风格)简化表示。(对于非紧急卡片,CDS 客户端可以隐藏这些详细信息,直到用户单击“查看更多详细信息…”等链接)。
indicator 必须 string 这张卡片传达的内容的紧迫性/重要性。 允许的值按紧急程度的增加顺序为:info、warning、critical。 CDS 客户端可以使用此字段来帮助做出 UI 显示决策,例如排序顺序或着色。
source 必须 object 此卡片上显示的信息来源的分组结构。 来源应该是卡片所代表的决策支持的主要指导来源。
……     其他属性参考标准规范

响应消息返回恰当的HTTP状态代码。

  • 如果执行成功,返回200 OK状态码。
  • 如果执行失败,则应返回4xx和5xx HTTP错误代码。
  • 返回412,先决条件失败,原因是“CDS 服务无法通过预取请求或直接调用 FHIR 服务器检索必要的 FHIR 数据来执行其决策支持”。
示例
  • 请求消息
POST /cds-services/patient-greeting HTTP/1.1
Host: fhir-org-cds-services.appspot.com
Content-Type: application/json

{
  "hookInstance": "d085084b-4ac6-432b-b1e2-6d702dcf4680",
  "hook": "patient-view",
  "fhirServer": "https://launch.smarthealthit.org/v/r2/fhir",
  "context": {
    "patientId": "smart-1288992",
    "userId": "Practitioner/COREPRACTITIONER1"
  },
  "prefetch": {
    "patient": {
      "resourceType": "Patient",
      "id": "smart-1288992",
      "meta": {
        "versionId": "634",
        "lastUpdated": "2021-05-12T02:30:37.942-04:00",
        "tag": [
          {
            "system": "https://smarthealthit.org/tags",
            "code": "smart-8-2017"
          }
        ]
      },
      "text": {
        "status": "generated",
        "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"> <p> Daniel Adams </p> </div>"
      },
      "identifier": [
        {
          "use": "usual",
          "type": {
            "coding": [
              {
                "system": "http://hl7.org/fhir/v2/0203",
                "code": "MR",
                "display": "Medical record number"
              }
            ],
            "text": "Medical record number"
          },
          "system": "http://hospital.smarthealthit.org",
          "value": "1288992"
        }
      ],
      "active": true,
      "name": [
        {
          "use": "official",
          "family": [
            "Adams"
          ],
          "given": [
            "Daniel",
            "X."
          ]
        }
      ],
      "telecom": [
        {
          "system": "email",
          "value": "daniel.adams@example.com"
        }
      ],
      "gender": "male",
      "birthDate": "1929-08-16",
      "address": [
        {
          "use": "home",
          "line": [
            "1 Hill AveApt 14"
          ],
          "city": "Tulsa",
          "state": "OK",
          "postalCode": "74117",
          "country": "USA"
        }
      ]
    }
  }
}
  • 响应消息
{
    "cards": [
        {
            "uuid": "39d53408-9995-44ec-9741-00122c07bc2d",
            "summary": "Now seeing: Daniel",
            "source": {
                "label": "Patient greeting service"
            },
            "indicator": "info"
        }
    ]
}

CDS医嘱选择

本交易由CDS客户端和CDS服务端使用。 调用地址:

POST {baseUrl}/cds-services/{service.id}
请求消息

CDS客户端触发调用医嘱选择服务时context属性如下:

字段 可选性 预取令牌 类型 描述
userId 必须 string 当前用户的id。对于这个钩子,用户应该是 Practitioner 类型。例如 Practitioner/123。
patientId 必须 string 上下文中当前患者的 FHIR Patient.id。
encounterId 可选 string 上下文中当前就诊的 FHIR Encounter.id
selections 必须 array 新选择的医嘱的 FHIR id。 selections 字段引用了 DraftOrders Bundle 中的 FHIR 资源。 例如,MedicationRequest/103。
draftOrders 必须 object 资源MedicationRequest, NutritionOrder, ServiceRequest, VisionPrescription组成的Bundle
响应消息

返回一组cards对象组成的数组。 每一个Card应该包含下列属性。

字段 可选性 类型 描述
uuid O string 卡的唯一标识符。可用于审核和记录卡,并应包含在对 CDS 服务的反馈端点的任何后续调用中。
summary R string 一个句子,少于140个字符的摘要消息,用于在此卡片内向用户显示。
detail O string 可选的详细信息显示;如果提供,则必须以(GitHub 风格)简化表示。(对于非紧急卡片,CDS 客户端可以隐藏这些详细信息,直到用户单击“查看更多详细信息…”等链接)。
indicator R string 这张卡片传达的内容的紧迫性/重要性。 允许的值按紧急程度的增加顺序为:info、warning、critical。 CDS 客户端可以使用此字段来帮助做出 UI 显示决策,例如排序顺序或着色。
source R object 此卡片上显示的信息来源的分组结构。 来源应该是卡片所代表的决策支持的主要指导来源。
     

响应消息返回恰当的HTTP状态代码。

  • 如果执行成功,返回200 OK状态码。
  • 如果执行失败,则应返回4xx和5xx HTTP错误代码。
  • 返回412,先决条件失败,原因是“CDS 服务无法通过预取请求或直接调用 FHIR 服务器检索必要的 FHIR 数据来执行其决策支持”。
示例
  • 请求消息(R5- NutritionOrder\MedicationRequest)
POST /cds-services/cms-price-check HTTP/1.1
Host: fhir-org-cds-services.appspot.com
Content-Type: application/json
Cache-Control: no-cache

{
    "context":{
        "userId":"Practitioner/123",
        "patientId":"1288992",
        "encounterId":"89284",
        "selections":[
            "NutritionOrder/pureeddiet-simple",
            "MedicationRequest/smart-MedicationRequest-103"
        ],
        "draftOrders":{
            "resourceType":"Bundle",
            "entry":[
                {
                    "resource":{
                        "resourceType":"NutritionOrder",
                        "id":"pureeddiet-simple",
                        "identifier":[
                            {
                                "system":"http://goodhealthhospital.org/nutrition-requests",
                                "value":"123"
                            }
                        ],
                        "status":"draft",
                        "patient":{
                            "reference":"Patient/1288992"
                        },
                        "dateTime":"2015-02-03",
                        "orderer":{
                            "reference":"Practitioner/example",
                            "display":"Dr Adam Careful"
                        },
                        "oralDiet":{
                            "type":[
                                {
                                    "coding":[
                                        {
                                            "system":"http://snomed.info/sct",
                                            "code":"226211001",
                                            "display":"Pureed diet"
                                        },
                                        {
                                            "system":"http://goodhealthhospital.org/diet-type-codes",
                                            "code":"1010",
                                            "display":"Pureed diet"
                                        }
                                    ],
                                    "text":"Pureed diet"
                                }
                            ],
                            "schedule":[
                                {
                                    "repeat":{
                                        "boundsPeriod":{
                                            "start":"2015-02-10",
                                            "end":"2015-02-23"
                                        },
                                        "frequency":3,
                                        "period":1,
                                        "periodUnit":"d"
                                    }
                                }
                            ],
                            "texture":[
                                {
                                    "modifier":{
                                        "coding":[
                                            {
                                                "system":"http://snomed.info/sct",
                                                "code":"228055009",
                                                "display":"Liquidized food"
                                            }
                                        ],
                                        "text":"Pureed"
                                    }
                                }
                            ],
                            "fluidConsistencyType":[
                                {
                                    "coding":[
                                        {
                                            "system":"http://snomed.info/sct",
                                            "code":"439021000124105",
                                            "display":"Dietary liquid consistency - nectar thick liquid"
                                        }
                                    ],
                                    "text":"Nectar thick liquids"
                                }
                            ]
                        },
                        "supplement":[
                            {
                                "type":{
                                    "coding":[
                                        {
                                            "system":"http://snomed.info/sct",
                                            "code":"442971000124100",
                                            "display":"Adult high energy formula"
                                        },
                                        {
                                            "system":"http://goodhealthhospital.org/supplement-type-codes",
                                            "code":"1040",
                                            "display":"Adult high energy pudding"
                                        }
                                    ],
                                    "text":"Adult high energy pudding"
                                },
                                "productName":"Ensure Pudding 4 oz container",
                                "instruction":"Ensure Pudding at breakfast, lunch, supper"
                            }
                        ]
                    }
                },
                {
                    "resource":{
                        "resourceType":"MedicationRequest",
                        "id":"smart-MedicationRequest-103",
                        "meta":{
                            "lastUpdated":"2015-02-03T13:25:40.845-04:00"
                        },
                        "text":{
                            "status":"generated",
                            "div":"&lt;div xmlns=\"http://www.w3.org/1999/xhtml\"&gt;Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension (rxnorm: 617993)&lt;/div&gt;"
                        },
                        "status":"draft",
                        "intent":"order",
                        "medicationCodeableConcept":{
                            "coding":[
                                {
                                    "system":"http://www.nlm.nih.gov/research/umls/rxnorm",
                                    "code":"617993",
                                    "display":"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension"
                                }
                            ],
                            "text":"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension"
                        },
                        "subject":{
                            "reference":"Patient/1288992"
                        },
                        "dosageInstruction":[
                            {
                                "text":"5 mL bid x 10 days",
                                "timing":{
                                    "repeat":{
                                        "boundsPeriod":{
                                            "start":"2015-02-04",
                                            "end":"2015-02-14"
                                        },
                                        "frequency":2,
                                        "period":1,
                                        "periodUnit":"d"
                                    }
                                },
                                "doseAndRate":{
                                    "doseQuantity":{
                                        "value":5,
                                        "unit":"mL",
                                        "system":"http://unitsofmeasure.org",
                                        "code":"mL"
                                    }
                                }
                            }
                        ],
                        "dispenseRequest":{
                            "numberOfRepeatsAllowed":1,
                            "quantity":{
                                "value":1,
                                "unit":"mL",
                                "system":"http://unitsofmeasure.org",
                                "code":"mL"
                            },
                            "expectedSupplyDuration":{
                                "value":10,
                                "unit":"days",
                                "system":"http://unitsofmeasure.org",
                                "code":"d"
                            }
                        }
                    }
                }
            ]
        }
    }
}
  • 响应消息
{
    "cards": [
        {
            "uuid": "77080d18-98b0-4f6f-997f-12fd4efff2e9",
            "summary": "Pureed diet, Adult high energy pudding",
            "source": {
                "label": "pureed diet simple"
            },
            "indicator": "info"
        },
        {
            "uuid": "722de2c0-e74b-4d22-bb48-a5e1deade5b9",
            "summary": "Cost: $6.47",
            "source": {
                "label": "CMS Public Use Files"
            },
            "indicator": "info"
        }
    ]
}

测试步骤

条件:相关资源(patient、encounter、medicationRequest等)已存在,提供JSON或XML格式。 动作:支持针对服务发现、获取患者信息、医嘱选择服务的CDS客户端、CDS服务端角色的交易,通过POSTMAN等工具验证;

2.5.1 服务发现 测试动作:客户端发起服务发现交易查询支持的服务列表,调用服务器接口,服务器返回支持的服务列表内容给客户端

前置条件:测试前,服务端已具备相应服务

验证标准:正确返回服务列表内容,必须包含获取患者信息和医嘱选择服务

2.5.2 获取患者信息 测试动作:客户端发起获取患者信息交易查询患者信息,调用服务器接口,服务器返回该患者的资源内容给客户端,客户端进行内容展示

前置条件:测试前,服务器端已具备患者资源等

验证标准:正确返回相应的卡片信息并进行可视化展示

2.5.3 医嘱选择 测试动作:客户端发起医嘱选择交易获取医嘱信息,调用服务器接口,服务器返回医嘱资源列表给客户端,客户端进行内容展示

前置条件:测试前,服务器端已具备患者资源、医嘱资源等

验证标准:正确返回相应的卡片信息并进行可视化展示