CDS Hooks - 規範 - 2

 進入無聊的階段，卻是實作最重要的階段。

實作CDS的整個過程，可以粗分「Discovery」、「Request CDS」、「CDS Response」與「Feedback」四個階段。（先把OAuth的部分屏除）

Discovery

CDS Client呼叫 <--> CDS Server實作

 Endpoint: GET {baseURL}/cds-services

Response Object:

註：

1.  想看完整有Swagger文件：Swagger Editor。
2. 都是JSON格式。
3. 注意Type是Primitive type, Object還是Array。 

hook

這個欄位是宣告兩端要共同遵守的鍵值變數組合(Context)。最常見的就是patient-view，他要求雙方有userId(R)、patientId(R)與encounterId(O)。這些鍵值欄位會以「prefetch tokens」的形式應用於prefetch欄位（後敘）中。所謂prefetch tokens就是用{{ }}包覆鍵值變數。

title

這個欄位可有可無，純粹用來給人看，由CDS Client決定要不要去呈現他。

description 

這個欄位反而是必要欄位，用來描述這個Hook服務的主要任務是什麼。

id

這個欄位非常重要，而且要小心設計。這個會是URL的一部分，也就是呼叫這個服務的路徑。所以，他必須要唯一。{baseUrl}/cds-services/{id}。

prefetch

這個欄位雖為Optional，卻是非常重要的欄位。CDS Server端告知CDS Client端，若要使用此服務，請你要提供哪些FHIR Resource。這個欄位內容的表達方式，有一個專有名稱為「Prefetch Template」是否能看懂且會用，又要用得好，就是看你FHIR的功力了。後面會專節說明。 

Discovery 範例

為避免一頭霧水，提供規範書的範例參考。這由CDS Server端實作，為/cds-services的回應內容。

{ "services": [ { "hook": "patient-view", "title": "Static CDS Service Example", "description": "An example of a CDS Service that returns a static set of cards", "id": "static-patient-greeter", "prefetch": { "patientToGreet": "Patient/{{context.patientId}}" } }, { "hook": "medication-prescribe", "title": "Medication Echo CDS Service", "description": "An example of a CDS Service that simply echos the medication being prescribed", "id": "medication-echo", "prefetch": { "patient": "Patient/{{context.patientId}}", "medications": "MedicationRequest?patient={{context.patientId}}" } } ] }

提醒，這個id與prefetch必須配對好，Server端要記住。當Client用某Id過來時，要知道他可能會帶什麼prefetch，別接錯了。

Prefetch Template

這段可能是CDS Hook最關鍵的地方。講到這先補充一下FHIR的Interactions。

CDS Hooks的Prefetch Template他就是FHIR read與search的機制。(另外支援的機制在後面規範會提到)所以，懂FHIR愈多，就能寫個漂亮的Prefetch Template，CDS Server端能要來的資料就更精確。

在官方文件就提供了一個範例：

{ "prefetch": { "hemoglobin-a1c": "Observation?patient={{context.patientId}}&code=4548-4&_count=1&sort:desc=date" } }

我非臨床人員，就不便多作解釋。不過，我可以跟妳說上述稱之為search機制。

一般最常用的就是

{ "prefetch": { "patient": "Patient/{{context.patientId}}", "user": "{{context.userId}}" } }

這是read機制。那個被{{ }}圍起來的就是prefetch Token。能有哪些可用，就看你是引用哪個Hooks規範。

先偷偷展示，回應會是長什麼樣子？（這是由CDS Client負責產生的）

{ "prefetch": { "patient":{ "resourceType": "Patient", "gender": "male", "birthDate": "1974-12-25", "...": "<snipped for brevity>" }, "hemoglobin-a1c": { "resourceType": "Bundle", "type": "searchset", "entry": [{ "resource": { "resourceType": "Observation", "code": { "coding": [{ "system": "http://loinc.org", "code": "4548-4", "display": "Hemoglobin A1c" }] }, "...": "<snipped for brevity>" } }] } } }