HealthLake에 대한 FHIR $questionnaire-package 작업

$questionnaire-package 작업은 FHIR 설문과 설문을 렌더링하고 처리하는 데 필요한 모든 종속성이 포함된 포괄적인 번들을 검색합니다. 이 작업은 Da Vinci 설명서 템플릿 및 규칙(DTR) 구현 가이드를 구현하여 의료 워크플로의 설명서 요구 사항에 맞게 동적 양식 렌더링을 활성화합니다.

작동 방식

사용 사례

API 엔드포인트

POST /datastore/{datastoreId}/r4/Questionnaire/$questionnaire-package  
Content-Type: application/fhir+json

요청 파라미터

입력 파라미터

요청 본문에는 다음 파라미터와 함께 FHIR 파라미터 리소스가 포함되어야 합니다.

파라미터 검증 규칙

다음 중 하나 이상을 제공해야 합니다(필수 외에도 coverage).

유효한 요청 조합:

요청 예제

POST /datastore/example-datastore/r4/Questionnaire/$questionnaire-package  
Content-Type: application/fhir+json  
Authorization: Bearer <your-token>  
  
{  
  "resourceType": "Parameters",  
  "parameter": [  
    {  
      "name": "coverage",  
      "resource": {  
        "resourceType": "Coverage",  
        "id": "example-coverage",  
        "status": "active",  
        "beneficiary": {  
          "reference": "Patient/example-patient"  
        },  
        "payor": [{  
          "reference": "Organization/example-payer"  
        }],  
        "class": [{  
          "type": {  
            "coding": [{  
              "system": "http://terminology.hl7.org/CodeSystem/coverage-class",  
              "code": "group"  
            }]  
          },  
          "value": "12345"  
        }]  
      }  
    },  
    {  
      "name": "questionnaire",  
      "valueCanonical": "http://example.org/fhir/Questionnaire/home-oxygen-therapy|2.0"  
    },  
    {  
      "name": "order",  
      "resource": {  
        "resourceType": "ServiceRequest",  
        "id": "example-service-request",  
        "status": "active",  
        "intent": "order",  
        "code": {  
          "coding": [{  
            "system": "http://www.ama-assn.org/go/cpt",  
            "code": "94660",  
            "display": "Continuous positive airway pressure ventilation (CPAP)"  
          }]  
        },  
        "subject": {  
          "reference": "Patient/example-patient"  
        }  
      }  
    },  
    {  
      "name": "changedSince",  
      "valueDateTime": "2024-01-01T00:00:00Z"  
    }  
  ]  
}

응답 형식

성공 응답(200 OK)

작업은 하나 이상의 패키지 번들이 포함된 FHIR 파라미터 리소스를 반환합니다. 각 패키지 번들에는 다음이 포함됩니다.

{  
  "resourceType": "Parameters",  
  "parameter": [  
    {  
      "name": "PackageBundle",  
      "resource": {  
        "resourceType": "Bundle",  
        "id": "questionnaire-package-example",  
        "meta": {  
          "profile": ["http://hl7.org/fhir/us/davinci-dtr/StructureDefinition/DTR-QPackageBundle"]  
        },  
        "type": "collection",  
        "timestamp": "2024-03-15T10:30:00Z",  
        "entry": [  
          {  
            "fullUrl": "http://example.org/fhir/Questionnaire/home-oxygen-therapy",  
            "resource": {  
              "resourceType": "Questionnaire",  
              "id": "home-oxygen-therapy",  
              "url": "http://example.org/fhir/Questionnaire/home-oxygen-therapy",  
              "version": "2.0",  
              "status": "active",  
              "title": "Home Oxygen Therapy Documentation",  
              "item": [  
                {  
                  "linkId": "1",  
                  "text": "Patient diagnosis",  
                  "type": "choice",  
                  "answerValueSet": "http://example.org/fhir/ValueSet/oxygen-diagnoses"  
                }  
              ]  
            }  
          },  
          {  
            "fullUrl": "http://example.org/fhir/Library/oxygen-prepopulation",  
            "resource": {  
              "resourceType": "Library",  
              "id": "oxygen-prepopulation",  
              "url": "http://example.org/fhir/Library/oxygen-prepopulation",  
              "version": "1.0",  
              "type": {  
                "coding": [{  
                  "system": "http://terminology.hl7.org/CodeSystem/library-type",  
                  "code": "logic-library"  
                }]  
              },  
              "content": [{  
                "contentType": "text/cql",  
                "data": "bGlicmFyeSBPeHlnZW5QcmVwb3B1bGF0aW9u..."  
              }]  
            }  
          },  
          {  
            "fullUrl": "http://example.org/fhir/ValueSet/oxygen-diagnoses",  
            "resource": {  
              "resourceType": "ValueSet",  
              "id": "oxygen-diagnoses",  
              "url": "http://example.org/fhir/ValueSet/oxygen-diagnoses",  
              "status": "active",  
              "expansion": {  
                "timestamp": "2024-03-15T10:30:00Z",  
                "contains": [  
                  {  
                    "system": "http://hl7.org/fhir/sid/icd-10",  
                    "code": "J44.0",  
                    "display": "COPD with acute lower respiratory infection"  
                  },  
                  {  
                    "system": "http://hl7.org/fhir/sid/icd-10",  
                    "code": "J96.01",  
                    "display": "Acute respiratory failure with hypoxia"  
                  }  
                ]  
              }  
            }  
          },  
          {  
            "fullUrl": "http://example.org/fhir/QuestionnaireResponse/example-prepopulated",  
            "resource": {  
              "resourceType": "QuestionnaireResponse",  
              "id": "example-prepopulated",  
              "questionnaire": "http://example.org/fhir/Questionnaire/home-oxygen-therapy|2.0",  
              "status": "in-progress",  
              "subject": {  
                "reference": "Patient/example-patient"  
              },  
              "basedOn": [{  
                "reference": "ServiceRequest/example-service-request"  
              }],  
              "item": [  
                {  
                  "linkId": "1",  
                  "text": "Patient diagnosis",  
                  "answer": [{  
                    "valueCoding": {  
                      "system": "http://hl7.org/fhir/sid/icd-10",  
                      "code": "J44.0",  
                      "display": "COPD with acute lower respiratory infection"  
                    }  
                  }]  
                }  
              ]  
            }  
          }  
        ]  
      }  
    },  
    {  
      "name": "Outcome",  
      "resource": {  
        "resourceType": "OperationOutcome",  
        "issue": [{  
          "severity": "information",  
          "code": "informational",  
          "details": {  
            "text": "Successfully retrieved questionnaire package"  
          }  
        }]  
      }  
    }  
  ]  
}

작업 워크플로

HealthLake가 요청을 처리하는 방법

를 호출하면 $questionnaire-package HealthLake는 다음 단계를 수행합니다.

결과: 렌더링 준비가 완료된 독립형 패키지입니다.

오류 응답

400 잘못된 요청

요청 검증에 실패하면 반환됩니다.

{  
  "resourceType": "OperationOutcome",  
  "issue": [{  
    "severity": "error",  
    "code": "required",  
    "details": {  
      "text": "At least one of 'questionnaire' or 'order' must be provided along with 'coverage'"  
    }  
  }]  
}

424 종속성 실패

종속 리소스를 검색할 수 없을 때 반환됩니다.

{  
  "resourceType": "OperationOutcome",  
  "issue": [{  
    "severity": "warning",  
    "code": "not-found",  
    "details": {  
      "text": "Referenced Library 'http://example.org/fhir/Library/missing-library' could not be retrieved"  
    }  
  }]  
}

401 권한이 없음

인증 자격 증명이 누락되거나 유효하지 않을 때 반환됩니다.

403 금지됨

인증된 사용자에게 요청된 리소스에 액세스할 수 있는 권한이 없는 경우 반환됩니다.

406 허용되지 않음

요청된 콘텐츠 유형을 제공할 수 없을 때 반환됩니다.

409 충돌

버전 또는 동시성 충돌이 있을 때 반환됩니다.

410 사라짐

요청된 리소스가 영구적으로 삭제되면 반환됩니다.

429 요청이 너무 많음

속도 제한을 초과하면 반환됩니다.

500 Internal Server Error

예기치 않은 서버 오류가 발생할 때 반환됩니다.

501 구현되지 않음

요청된 작업이 아직 구현되지 않은 경우 반환됩니다.

검증 규칙

입력 검증

QuestionnaireResponse 검증

리소스 중복 제거

성능 사양

필수 권한

$questionnaire-package 작업을 사용하려면 IAM 역할에 다음이 있는지 확인합니다.

FHIR 범위에 대한 SMART

최소 필수 범위:

중요한 구현 참고 사항

리소스 검색 전략

설문 조사 식별 우선 순위:

종속성 해결

CQL 라이브러리:

ValueSets:

QuestionnaireResponse 사전 모집단

작업은 다음과 같은 경우 미리 채워진 데이터가 포함된 QuestionnaireResponse를 반환할 수 있습니다.

QuestionnaireResponse 검색 기준:

리소스 필터링 변경

changedSince 파라미터가 제공되는 경우:

여러 패키지 번들

작업은 다음과 같은 경우 여러 패키지 번들을 반환할 수 있습니다.

각 패키지 번들에는 필요한 모든 종속성이 포함되어 있습니다.

일반 사용 사례

사용 사례 1: 사전 승인 설명서

시나리오: 공급자는 사전 승인을 받기 전에 가정용 항기 치료용 설명서를 수집해야 합니다.

{  
  "resourceType": "Parameters",  
  "parameter": [  
    {  
      "name": "coverage",  
      "resource": { /* Patient's insurance coverage */ }  
    },  
    {  
      "name": "order",  
      "resource": {  
        "resourceType": "ServiceRequest",  
        "code": {  
          "coding": [{  
            "system": "http://www.ama-assn.org/go/cpt",  
            "code": "94660"  
          }]  
        }  
      }  
    }  
  ]  
}

결과: 환자 바이탈과 EHR의 진단 코드로 미리 채워진, 항산기 치료 설문지가 포함된 패키지를 반환합니다.

사용 사례 2: 특정 설문 조사 버전 검색

시나리오: 규정 준수를 위해 공급자에게 특정 버전의 설문지가 필요합니다.

{  
  "resourceType": "Parameters",  
  "parameter": [  
    {  
      "name": "coverage",  
      "resource": { /* Coverage resource */ }  
    },  
    {  
      "name": "questionnaire",  
      "valueCanonical": "http://example.org/fhir/Questionnaire/dme-request|3.1.0"  
    }  
  ]  
}

결과: 모든 종속성과 함께 정확히 버전 3.1.0의 Dell 요청 설문지를 반환합니다.

사용 사례 3: 업데이트 확인

시나리오: 공급자는 마지막 검색 이후 업데이트된 설문지 리소스가 있는지 확인하려고 합니다.

{  
  "resourceType": "Parameters",  
  "parameter": [  
    {  
      "name": "coverage",  
      "resource": { /* Coverage resource */ }  
    },  
    {  
      "name": "questionnaire",  
      "valueCanonical": "http://example.org/fhir/Questionnaire/medication-request"  
    },  
    {  
      "name": "changedSince",  
      "valueDateTime": "2024-03-01T00:00:00Z"  
    }  
  ]  
}

결과: 2024년 3월 1일 이후에 수정된 리소스만 반환하거나 변경되지 않은 경우 빈 패키지를 반환합니다.

사용 사례 4: 여러 주문

시나리오: 공급자가 서로 다른 설문지가 필요할 수 있는 여러 서비스 요청을 제출합니다.

{  
  "resourceType": "Parameters",  
  "parameter": [  
    {  
      "name": "coverage",  
      "resource": { /* Coverage resource */ }  
    },  
    {  
      "name": "order",  
      "resource": { /* ServiceRequest for imaging */ }  
    },  
    {  
      "name": "order",  
      "resource": { /* ServiceRequest for DME */ }  
    }  
  ]  
}

결과: 해당하는 각 설문에 대해 하나씩 여러 패키지 번들을 반환합니다.

다른 Da Vinci IGs와 통합

적용 범위 요구 사항 검색(CRD)

워크플로 통합:

사전 승인 지원(PAS)

워크플로 통합:

임상 데이터 교환(CDex)

워크플로 통합:

문제 해결 가이드

문제: 반환된 설문지 없음

가능한 원인:

솔루션

문제: 패키지의 종속성 누락

가능한 원인:

솔루션

문제: changedSince가 있는 빈 패키지

가능한 원인:

솔루션

문제: QuestionnaireResponse가 미리 채워지지 않음

가능한 원인:

솔루션

모범 사례

1. 버전URLs 사용

특정 설문지를 요청할 때는 항상 버전 번호를 지정하십시오.

{  
  "name": "questionnaire",  
  "valueCanonical": "http://example.org/fhir/Questionnaire/dme|2.1.0"  
}

이유: 일관성을 보장하고 설문이 업데이트될 때 예기치 않은 변경을 방지합니다.

2. 성능 측면에서 changedSince 활용

자주 액세스하는 설문지의 경우 changedSince를 사용하여 데이터 전송을 최소화합니다.

{  
  "name": "changedSince",  
  "valueDateTime": "2024-03-10T15:30:00Z"  
}

이유: 업데이트된 리소스만 검색하여 지연 시간과 대역폭 사용량을 줄입니다.

3. 전체 적용 범위 정보 포함

올바른 설문 선택을 위해 포괄적인 적용 범위 세부 정보를 제공합니다.

{  
  "name": "coverage",  
  "resource": {  
    "resourceType": "Coverage",  
    "beneficiary": { "reference": "Patient/123" },  
    "payor": [{ "reference": "Organization/payer-abc" }],  
    "class": [{ /* Group/plan information */ }]  
  }  
}

이유: HealthLake가 지급인별 설문지 및 요구 사항을 식별하는 데 도움이 됩니다.

관련 작업