HealthLake の FHIR $questionnaire-packageオペレーション

$questionnaire-package オペレーションは、FHIR アンケートとそのアンケートのレンダリングと処理に必要なすべての依存関係を含む包括的なバンドルを取得します。このオペレーションでは、Da Vinci ドキュメントテンプレートとルール (DTR) 実装ガイドを実装し、ヘルスケアワークフローのドキュメント要件の動的フォームレンダリングを有効にします。

仕組み

ユースケース

API エンドポイント

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

リクエストパラメータ

入力パラメータ

リクエスト本文には、次のパラメータを含む FHIR Parameters リソースが含まれている必要があります。

パラメータ検証ルール

次のいずれかを指定する必要があります (必須 に加えて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)

オペレーションは、1 つ以上のパッケージバンドルを含む FHIR Parameters リソースを返します。各パッケージバンドルには以下が含まれます。

{  
  "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 Bad Request

リクエストの検証が失敗したときに返されます。

{  
  "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 Unauthorized

認証情報がないか無効である場合に返されます。

403 Forbidden

認証されたユーザーに、リクエストされたリソースへのアクセス許可がない場合に返されます。

406 使用できません

リクエストされたコンテンツタイプを指定できない場合に返されます。

409 Conflict

バージョンまたは同時実行の競合がある場合に返されます。

410 終了

リクエストされたリソースが完全に削除されたときに返されます。

429 Too Many Requests

レート制限を超えたときに返されます。

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 から患者のバイタルと診断コードがあらかじめ入力されている、O2 度治療用アンケートを含むパッケージを返します。

ユースケース 2: 特定のアンケートバージョンを取得する

シナリオ: コンプライアンスのためにプロバイダーに特定のバージョンのアンケートが必要です。

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

結果: すべての依存関係を持つ DME リクエストアンケートのバージョン 3.1.0 を正確に返します。

ユースケース 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 */ }  
    }  
  ]  
}

結果: 該当するアンケートごとに 1 つずつ、複数のパッケージバンドルを返します。

他の Da Vinci IGs との統合

カバレッジ要件検出 (CRD)

ワークフロー統合:

事前認可サポート (PAS)

ワークフロー統合:

臨床データ交換 (CDex)

ワークフロー統合:

トラブルシューティングガイド

問題: アンケートが返されない

考えられる原因:

解決方法:

問題: パッケージに依存関係がない

考えられる原因:

解決方法:

問題: changedSince のパッケージが空

考えられる原因:

解決方法:

問題: QuestionnaireResponse が事前に入力されていません

考えられる原因:

解決方法:

ベストプラクティス

1. バージョンで正規 URLs を使用する

特定のアンケートをリクエストするときは、常にバージョン番号を指定します。

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

理由: 一貫性を確保し、アンケートが更新されたときの予期しない変更を防ぎます。

2. changedSince for Performance を活用する

頻繁にアクセス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 が支払者固有のアンケートと要件を特定するのに役立ちます。

関連の オペレーション