バルク FHIR コーディネータ
一般的な HL7® FHIR® 相互作用が、特定の患者に関する固有の情報を検索するのに対して FHIR バルク・データOpens in a new tabの相互作用は、FHIRリソース・サーバから患者全体にわたる大量のデータを抽出します。バルク FHIR の一般的な用途として、検査コホートの特定、公衆衛生、EHR から他の EHR へのデータ転送などがあります。
バルク FHIR コーディネータの概要
クライアントとの FHIR バルク・データの相互作用を簡潔にしてバルク・データ要求で FHIR サーバが過負荷にならないように、バルク・データ・クライアントと FHIR リソース・サーバ・エンドポイントの間では、インターシステムズのバルク FHIR コーディネータ (BFC) によってバルク・データ要求が仲介されます。ネイティブではバルク・データの相互作用をサポートしていない FHIR リソース・サーバへのバルク FHIR のエクスポートを、バルク FHIR コーディネータで容易にすることができます。
クライアントに代わり、バルク FHIR コーディネータが FHIR エンドポイントに FHIR リソースを要求し、それを受け取る場合、この処理はエクスポートとされます。
クライアントと FHIR エンドポイントとの相互作用をバルク FHIR コーディネータが仲介する様子を以下の図に示します。
バルク FHIR コーディネータと相互作用するには、BFC のホーム・ページを使用するか、バルク・データの REST クライアントを介します。
-
BFC のホーム・ページでは一組の構成を入力できます。バルク FHIR の構成のそれぞれで FHIR リソース・サーバのエンドポイントを特定し、承認のタイプやファイルの場所など、バルク・データの相互作用で使用する各種パラメータを定義します。すべてのリソースを返すことができて、患者とグループのエクスポートで Patient/$everything オペレーションをサポートするあらゆるシステムを FHIR エンドポイントとして使用できます。例えば、InterSystems IRIS for Health、InterSystems HealthShare Health Connect、InterSystems HealthShare Unified Care Record があります。
このホーム・ページでは、エクスポートの開始、エクスポート・ステータスの確認、エクスポートしたファイルのダウンロード、エクスポート・ログの確認もできます。
-
REST クライアントを使用すると、FHIR Bulk Data Export 仕様Opens in a new tabの説明にある各要求を実行できます。各バルク FHIR 構成は、次の 2 つのエンドポイントを提供します。
-
バルク FHIR エンドポイント — エクスポートとステータスをサポートし、要求を削除します。
-
ファイル・ストレージ・エンドポイント — ファイルのダウンロード要求をサポートします。
-
バルク FHIR コーディネータのホーム・ページ
バルク FHIR 構成を操作するには、[ホーム]→[Health]→[foundationNamespace]→[バルク FHIR コーディネータ] に移動します。
構成ごとに名前と一意のエンドポイントがあります。[構成]→[リスト] ページのアイコンを使用して、以下の各アクションを実行します。
アイコン | アクション | 注 |
---|---|---|
新規構成 | [編集] ページを開くか、JSON ファイルをインポートすることで、新しい構成を作成できます。 | |
エクスポートの表示 | 構成の [エクスポート] ビュー・ページが開き、進行中または完了したバルク FHIR エクスポートを確認して、新しいエクスポートを要求できます。 | |
コピー | 上記と同様の構成の [編集] ページが開きますが、Name と Endpoint に _copy が付加されている点が異なります。[次へ] ボタンを使用しながら構成ページの手順を 1 つずつ実行し、必要な調整を実施します。[レビュー] ページで [構成] をクリックして新しい構成を保存します。 | |
編集 | この構成の [編集] ページが開きます。[次へ] ボタンを使用しながら構成ページの手順を 1 つずつ実行し、必要な調整を実施します。[レビュー] ページで [構成] をクリックして変更を保存します。 | |
ダウンロード | 目的の構成の JSON 形式レコードを作成します。このファイルの名前は目的の構成と同じ名前になりますが、特殊文字はアンダースコアに置き換えられます。JSON 形式の構成をインポートするには、[新規構成] ボタンをクリックして [Import JSON] を選択し、参照コントロールを使用して目的のファイルを探します。 | |
削除 | テキスト・ボックスに表示されているとおりにエンドポイントの URL を入力し、それが間違いないことを確認して [削除] ボタンをクリックします。 |
バルク FHIR 構成の作成または編集
バルク FHIR 構成を作成または編集するには以下の手順に従います。
-
管理者特権を持つユーザとして InterSystems IRIS for Health にログインします。
-
[ホーム]→[Health]→[foundationNamespace]→[バルク FHIR コーディネータ] に移動します。
-
[バルク FHIR コーディネータ] ページで、既存の構成に対して または をクリックするか、[新規作成]、[新規構成] の順にクリックすることで、作成/編集ワークフローを呼び出します。
バルク FHIR 構成の作成/編集ワークフローは、以下の 5 つのページで構成されています。
作成/編集ワークフローの各ページで値を入力し、[次へ] をクリックして次のページへ移動します。最後のレビュー・ページで [構成] をクリックすると、バルク FHIR 構成が保存されます。以降の各セクションでは、さまざまな設定について説明します。
バルク FHIR の作成/編集ワークフロー : 設定構成
バルク FHIR 構成を対象とした作成/編集ワークフローの [構成設定] ページには以下の各設定があります。
使用する構成の一意な名前を入力します。主要なパラメータのいくつかを名前に使用すると、多数の構成からこの構成を区別しやすくなります。名前の指定は必須です。
要求を受け取ると直ちにエクスポート・ジョブを開始するには、このオプションを選択します。エクスポートを開始するために手動での承認を必要とする場合は、このオプションの選択を解除します。既定では選択されています。
このバルク FHIR エンドポイントの URL を入力します。この値の入力は必須で、各種構成で一意とする必要があります。/bulkFHIR/r4a のように相対的な値とします。この構成を保存するときに、REST エンドポイントとして機能するこの URL を使用して Web アプリが作成されます。
この構成を保存するときにその [Fetch Endpoint URL] から得られた読み取り専用フィールドです。その値は、例えば hl7.fhir.r4.core@4.0.1 です。
許可するエクスポートのタイプを以下から選択します。
-
[患者] — すべての患者に関連する FHIR リソース群
-
[グループ] — 指定したグループ・リソースのすべてのメンバに関連する FHIR リソース群。HS.BulkFHIR.Fetch.ODS.AdapterOpens in a new tab 取得アダプタでは、グループ・リソースは Unified Care Record コホートとして把握されます。
-
[システム] — 患者との関連性の有無にかかわらず、すべての FHIR リソース。返されたリソースを _type パラメータで制限した用語データのエクスポートやサーバのバックアップなどのユース・ケースがサポートされています。
格納されている ndjson ファイルが失効するまでの期間 (分)。既定値は 1440 分 (1 日) です。失効した ndjson ファイルは、既定で 1 時間に 1 回実行される Bulk FHIR expiration task によってすべて削除されます。
ndjson ファイルごとの最大サイズ (バイト)。エクスポートの際に、開いている ndjson ファイルのサイズがこの値に達すると、そのファイルは保存され、新しいファイルへのエクスポートが開始されます。既定値は 100 万バイトです。
フラッシュ間隔 (分)。エクスポートでこの時間が経過すると、開いている ndjson ファイルは保存され、新しいファイルに対するエクスポートが開始されます。既定値は 60 分です。
ストレージ・ファイル・アダプタに渡す前の一時ファイルを格納するディレクトリ。
バルク FHIR の作成/編集ワークフロー : 取得の構成
作成/編集ワークフローの [Fetch] ページでは以下の手順を実行できます。
取得の構成 : アダプタの選択
このフィールドへの入力は必須です。HS.BulkFHIR.Fetch.PureFHIR.AdapterOpens in a new tab または HS.BulkFHIR.Fetch.ODS.AdapterOpens in a new tab を選択します。ODS アダプタは Unified Care Record ODS に固有です。
取得の構成 : アダプタの構成
[Adapter Configuration] 見出しに示されている設定は、ODS 取得アダプタに対してのみ表示される Registry Webservice 設定を除き、すべてが PureFHIR 取得アダプタと ODS 取得アダプタの両方に対して表示されます。
FHIR エンドポイントの完全な URL。例えば、https://example.org/fhir/r4。このフィールドへの入力は必須です。
HTTPS を使用して FHIR エンドポイントと通信する方法を記述した、InterSystems IRIS の SSL/TLS クライアント構成。
この構成のエクスポート・オペレーションで扱う必要がある FHIR リソース・タイプをコンマ区切りで記述した既定のリスト。バルク・データ要求に _type クエリ・パラメータを使用することで、このリストをクライアントによってオーバーライドできます。このフィールドを空のままにすると、既定ですべてのリソース・タイプが扱われます。
FHIR エンドポイントに対して毎秒実行できる HTTP(S) 要求の最大数。この値は、構成のすべてのアクティブなエクスポート・オペレーションに共通で適用されるので、バルク FHIR コーディネータによって FHIR エンドポイントに発生する負荷を制限するために使用できます。秒あたり 10 件の要求が既定値です。
データの取得で FHIR エンドポイントに対して実行する HTTP(S) 要求ごとのタイムアウト値 (秒)。エクスポートするデータが大量で、FHIR エンドポイントのページ・サイズが大きい場合、取得でタイムアウト・エラーが発生するのであれば、このタイムアウトを長くします。既定値は 180 秒です。
取得処理の実行が割り当てられているバックグラウンド・ワーカ・ジョブの数。4 件のジョブが既定値です。
HS.BulkFHIR.Fetch.ODS.AdapterOpens in a new tab を使用するときは必ず指定します。Unified Care Record レジストリで Hub Web サービスを呼び出すときに使用する相互運用認証情報。
この認証情報は、Hub Web サービスの UCR サービス・レジストリ・エントリの Username Token Profile 設定と一致している必要があります。このサービス・レジストリ・エントリは baseURL/services/HS.Hub.HSWS.WebServices.cls を参照するので、これによって特定できます。多くの場合、このサービス・レジストリ・エントリの名前は HSREGISTRY です。HSREGISTRY サービス・レジストリ・エントリの Username Token Profile 設定の値は、一般的に HS_Services です。
実行時に Hub Web サービスを呼び出すときは、この認証情報のユーザ名とパスワードが使用されます。
HS.BulkFHIR.Fetch.ODS.AdapterOpens in a new tab を使用するときは必ず指定します。Unified Care Record レジストリの Hub Web サービス の URL。通常は、以下のとおりです。
https://UCRHost:Port/csp/healthshare/registryNamespace/services/HS.Hub.HSWS.WebServices.cls
バルク FHIR の作成/編集ワークフロー : ストレージの構成
バルク FHIR 構成を対象とした作成/編集ワークフローの [Storage Location] ページには以下の各設定があります。
このフィールドへの入力は必須です。HS.BulkFHIR.Storage.File.AdapterOpens in a new tab を選択します。
バルク・エクスポート・ファイルを提供する Web アプリケーション・ファイルの相対 URL パス (例 : /file または /bulkfhir/file)。異なる構成であっても同じネームスペースにあれば、使用する URL は同じです。
この URL はOpens in a new tab、Web サーバ構成によって異なります。複数の InterSystems IRIS for Health インスタンスに対して 1 つの Web サーバを使用する場合は、インスタンス接頭語を含めます。
エクスポートした FHIR リソースを収めた ndjson ファイルの格納先。指定しない場合は、既定で installDir/mgr/Temp/BulkFHIR/namespace/ になります。このディレクトリには、セッションごとに番号付きの名前を持つサブディレクトリがあります。各セッション・サブディレクトリには、リソース・グループのディレクトリとファイルがあります。ネームスペースごとに独立したディレクトリを使用する必要があります。セッション識別子が衝突する可能性があるからです。
バルク FHIR の作成/編集ワークフロー : 構成のレビューと検証
バルク FHIR 構成を対象とした作成/編集ワークフローの [レビュー] ページには、他のページにある各設定の値が表示されます。これらの設定をレビューし、[構成] をクリックしてバルク FHIR 構成を保存します。[構成] をクリックすると BFC によって各設定が検証され、対処を必要とする問題があるとそれが表示されます。各設定が検証に適合すると、必要な OAuth クライアント構成とサーバ記述が BFC によってすべて自動的に構成されます。
JSON を使用したバルク FHIR 構成のインポート
構成をインポートするには、[新規構成] ボタンをクリックして [Import JSON] を選択し、参照コントロールを使用して目的のファイルを探します。
以下では、バルク FHIR 構成向け JSON 仕様をセクション別で具体的に示しています。
-
空白のままとする単純なプロパティは除外できます。
-
JSON で使用されている角括弧は、値のコンマ区切りリストを入力できることを示しています。
-
JSON フラグメントのテキストの色は以下を示しています。
-
緑色のテキストは、引用符の中の文字列が想定されることを示します。
-
赤色のテキストは、数値が想定されることを示します。
-
オレンジ色のテキストは、ブーリアン値である true または false が想定されることを示します。
-
次の各ページの JSON 例をその後に示します。
[構成設定] ページの JSON 例
[認証タイプ] ページの JSON 例
基本的な承認アダプタ
OAuth アダプタ
[Fetch] ページの JSON 例
ODS 取得アダプタ
"fetch_config": { プロパティの終了部分は、"取得承認設定" を参照してください。
純粋な FHIR 取得アダプタ
"fetch_config": { プロパティの終了部分は、"取得承認設定" を参照してください。
取得承認設定
HTTP 取得承認
以下の JSON フラグメントは "fetch_config": { プロパティの終了部分です。
X-API 取得承認
以下の JSON フラグメントは "fetch_config": { プロパティの終了部分です。
OAuth 取得承認
以下の JSON フラグメントは "fetch_config": { プロパティの終了部分です。
[Storage Location] ページの JSON 例
バルク FHIR ホーム・ページからのエクスポート実行
クライアントに代わり、バルク FHIR コーディネータが FHIR エンドポイントにある FHIR リソース群を要求した場合、このアクションはエクスポートと呼ばれます。
ここでは以下の方法について説明します。
[エクスポート] ページへのアクセス
バルク FHIR エクスポートを開始または検査するには以下の手順に従います。
-
適切な特権を持つユーザとして InterSystems IRIS for Health にログインします。
-
[ホーム]→[Health]→[foundationNamespace]→[バルク FHIR コーディネータ] に移動します。
-
以下のいずれかの方法で [エクスポート] ページに移動します。
-
[エクスポート] リンクをクリックし、[エクスポート]→[リスト] ページを開いてすべてのエクスポートを表示します。
-
をクリックし、[エクスポート]→[表示] ページを開いて特定の構成のエクスポートを表示します。
-
[エクスポート] ページでは、進行中のエクスポートと完了したエクスポートのステータスを確認できます。以下の各アクションも実行できます。
アイコン | アクション | 注 |
---|---|---|
新規エクスポート要求 | 新規エクスポートを開始します。 | |
一時停止 | 進行中のエクスポートを一時停止します。 | |
再開 | 一時停止していたエクスポートを再開します。 | |
キャンセル | 進行中のエクスポートをキャンセルします。 | |
ログの表示 | 進行中のエクスポートまたは完了したエクスポートのログを表示します。[ログ]→[リスト] ページを開き、エクスポート・ログをフィルタ処理して表示できます。 | |
コピー | 完了したエクスポートの情報を使用して新しいエクスポートを作成します。 | |
ダウンロード | [エクスポート]→[Exported Files] ページを開きます。タイプ別に特定リソースの ndjson ファイルを検索してダウンロードできるほか、エクスポート・エラーもダウンロードできます。 |
エクスポート要求の開始
-
[エクスポート] ページで [New Export Request] をクリックしてエクスポートを開始します。
-
[構成] ドロップダウン・リストから BFC 構成を選択します。
-
[次へ] をクリックします。
-
[エクスポート] からエクスポートのタイプを選択します。[システム]、[グループ]、または [患者] を選択できます。
-
グループのエクスポートを選択した場合は、[Group ID] にグループ ID を入力します。Unified Care Report ODS では、コホート名がグループ ID になります。
-
必要に応じ、[Since] フィールドに YYYY-MM-DD の書式で日付を入力するか、日付選択機能を使用して日付を選択します。[Add Time] をクリックして時刻を入力することもできます。
-
[Export Now] をクリックするとエクスポートが始まります。
-
[エクスポート] ページの [処理中] テーブルにエクスポートが行として表示されます。進行中のエクスポートを一時停止、再開、またはキャンセルできます。ログを表示して、エクスポートの進行状況を確認することもできます。
完了したエクスポートの ndjson のダウンロード
-
[エクスポート] ページの [Completed Exports] ペインで必要に応じてフィルタ値を入力し、[適用] をクリックすると完了済みエクスポートのリストがフィルタ処理されます。
-
[Completed Exports] テーブルの目的の行で をクリックすると、そのエクスポートに存在するファイルの一覧が表示されます。エクスポートするファイルがリソース・タイプ別に分類されています。
-
一覧に表示されるファイルを少なくするには、必要に応じて検索語を入力します。
-
ndjson ファイルをダウンロードするには をクリックします。
エクスポート・ログの表示
バルク FHIR ワークフローの以下のコンポーネントで発生した各種イベントについて、エクスポート・ログに詳しい情報が記録されます。
コンポーネント | イベント・タイプ | 詳細 |
---|---|---|
BFC | session_action | アクション : 作成、開始、一時停止、再開、完了、失敗 (理由とスタック) |
BFC | flush | 理由 : サイズ、間隔、finalize_session |
取得 | rest_request | パス、rate_limit_time、http_response_time、http_status (理由、スタック) |
ストレージ | flush | 理由 : サイズ、間隔、finalize_session |
ストレージ | file_access | クライアント、ファイル |
セッションのエクスポート・ログを表示するには以下の手順に従います。
-
[エクスポート] ページで、[処理中] または [完了] が示されたセッションの行で をクリックします。または、[ログ] をクリックしてすべてのセッションのログを表示します。
-
必要に応じ、一覧に表示されるログを少なくするには、フィルタ値を入力して [適用] をクリックします。
-
をクリックすると特定のログ・ファイルが表示されます。
REST クライアントからのバルク FHIR エクスポート
クライアントに代わり、バルク FHIR コーディネータが FHIR エンドポイントにある FHIR リソース群を要求した場合、このアクションはエクスポートと呼ばれます。
ここでは以下の方法について説明します。
REST クライアントからの要求のエクスポート開始
REST クライアントからのバルク FHIR エクスポートを開始するには、目的のオペレーションを指定して BFC エンドポイントに GET 要求を送信します。以下に例を挙げます。
-
システム — GET https://bfcEndpoint/$export
-
患者 — GET https://bfcEndpoint/Patient/$export
-
グループ — GET https://bfcEndpoint/Group/groupID/$export
この BFC 構成で OAuth の Auth アダプタを使用している場合は、以下を指定してアクセス・トークンを取得します。
-
OAuth サーバのアクセス・トークン・エンドポイント :
issuerEndpoint/token
必要に応じて対象ユーザ :
?aud=https://bfcEndpoint
-
BFC 構成の [認証タイプ] タブに挙げられているいずれかの OAuth クライアントのクライアント ID とクライアント秘密鍵。
-
OAuth クライアントでサポートされている付与タイプ (InterSystems IRIS では、OAuth クライアント構成の [一般] タブで選択した必須付与タイプのいずれかです)。
-
スコープ。最小限必要なスコープは system/Patient.read です。system/*.read を指定するとすべてが許可されます。
OAuth を使用して患者をエクスポートする例を以下に示します。
$export では、以下のオプション・パラメータを使用できます。
BFC では、改行区切りで JSON (ndjson) ファイルがエクスポートされます。
application/fhir+ndjson 値と、その省略名である application/ndjson と ndjson の値を使用できます。
以下の “FHIR 瞬間時点” 形式で指定した時間の経過後にリソースの状態が変化すると、そのリソースが応答に追加されます。
YYYY-MM-DDThh:mm:ss.sss+zz:zz
エクスポートの対象とする FHIR リソース・タイプのコンマ区切りリスト。既定は、構成した取得アダプタでサポートされているすべてのリソース・タイプです。
REST クライアントからのエクスポートのステータス確認
最初の GET 要求に対する応答ヘッダには、以下の形式で URL を指定した CONTENT-LOCATION キーがあります。
bfcEndpoint/status/sessionNumber
CONTENT-LOCATION の URL へ定期的に GET 要求を送信して、バルク FHIR エクスポート・セッションのステータスを取得します。
以下のようなステータス応答が返されます。
-
BFC でエクスポートが処理されています。
-
応答ヘッダには、値を in-progress とした X-PROGRESS キーが追加されます。
-
エクスポートが完了したので、ファイルをダウンロードできます。
-
応答ヘッダには、BFC ファイル・サーバに ndjson ファイルが保持されている期間を示した EXPIRES キーが追加されます。
-
応答本文には、BFC ファイル・サーバ上に格納されている ndjson ファイルの URL が記述されます。返されるリソース・タイプごとに 1 つ以上のファイルがあります。
-
BFC でエラーが発生しました。
完了したエクスポートの ndjson のダウンロード
受信した応答ヘッダに Status: 200 OK があれば、BFC ファイル・サーバから目的のファイルをダウンロードできます。これらのファイルを取得するには、ファイルの URL ごとに GET 要求を送信します。
この BFC 構成で OAuth の Auth アダプタを使用している場合は、以下を指定して新しいアクセス・トークンを取得します。
-
BFC 構成の [取得] タブで特定した付与タイプ。
-
OAuth サーバのアクセス・トークン・エンドポイント :
issuerEndpoint/token
必要に応じて対象ユーザ :
?aud=https://bfcFileEndpoint
-
BFC 構成の [認証タイプ] タブに挙げられているいずれかの OAuth クライアントのクライアント ID とクライアント秘密鍵。
-
スコープ。ファイルのダウンロードでは一般的に user/*.read です。
以下に例を示します。
エクスポートのキャンセル
進行中のエクスポートをキャンセルするには、CONTENT-LOCATION URL に DELETE 要求を送信します。削除が成功した場合、BFC は HTTP ステータス・コード “202 Accepted” を返します。他のステータス・コードは、エラーを示します。
バルク FHIR のロールとリソース
バルク FHIR コーディネータは、ロールベースのアクセスを使用します。
バルク FHIR ロール
バルク FHIR コーディネータは、以下のユーザ・ロールを提供します。
%HS_BFC_Exporter ロールには以下の許可が付与されています。
-
ユーザが承認済みユーザとして指定されている構成上で患者またはグループのエクスポートを表示し、また実行します。
-
これらのエクスポートを一時停止、再開、またはキャンセルします。また、これらのエクスポートのログを表示し、ダウンロードします。
OAuth クライアント構成と照合するために作成するダミーの InterSystems IRIS ユーザそれぞれに対して、(ダミー・ユーザを構成の承認済みユーザにすることに加え) このロールを割り当てます。
%HS_BFC_Exporter は、OAuth クライアントにロールを対応付けるダミー・ユーザに使用することを主眼としています。したがって、このロールのみのユーザは、管理ポータルのメニューからバルク FHIR コーディネータのホーム・ページにアクセスできません。実際のユーザにこのロールを割り当てる場合は、BFC Foundation ネームスペースをそのユーザの開始ネームスペースとするか、そのユーザにポータルで BFC ホーム・ページへの直接リンクを通知します。
このロールと %HS_BFC_Export_Manage ロールを割り当てられたユーザは、すべての構成上で患者またはグループのエクスポートを開始でき、自身が開始したエクスポートのログを表示し、ダウンロードできます。また、ポータルのホーム・ページにもアクセスできます。
%HS_BFC_Export_Manage ロールには以下の許可が付与されています。
-
すべての構成とすべてのエクスポートを表示します。
-
構成の作成、エクスポートの開始、エクスポート・ログの表示はできません。
%HS_BFC_Exporter と共に割り当てることで特権を拡張できます。
%HS_BFC_Administrator ロールには以下の許可が付与されています。
-
すべての構成を表示、作成、編集、コピー、削除します。
-
システムのエクスポートをサポートしているあらゆる構成上で、そのエクスポートを実行します。
-
すべてのエクスポートを表示、一時停止、停止、再開、キャンセルし、そのログを表示またはダウンロードします。
-
自身で開始したエクスポートをダウンロードします。
%HS_BFC_Download_Manage と共に割り当てることで、すべてのエクスポートのファイルをダウンロードできます。
%HS_BFC_Download_Manage ロールには以下の許可が付与されています。
-
すべてのエクスポートのファイルをダウンロードします。
%HS_BFC_Administrator の特権を拡張するために使用します。
[ホーム]→[セキュリティ]→[ロール] へ移動すると、上記の各ロールに関連付けられたリソースと特権を確認できます。
バルク FHIR のリソースと権限
バルク FHIR コーディネータ内のアクションは、以下の権限に関連付けられています。
リソース | 特権 |
---|---|
%HS_BFC_Configuration |
|
%HS_BFC_Download_Manage |
|
%HS_BFC_Export_Download |
|
%HS_BFC_Export_Group |
|
%HS_BFC_Export_Log |
|
%HS_BFC_Export_Manage |
|
%HS_BFC_Export_Patient |
|
%HS_BFC_Export_Status |
|
%HS_BFC_Export_System |
|
%HS_BFC_Log_Manage |
|
[ホーム]→[セキュリティ]→[リソース] に移動して、これらのリソースと権限の説明を確認することもできます。
バルク FHIR コーディネータ向け OAuth 2.0 サーバの作成
バルク FHIR REST クライアントとバルク FHIR コーディネータ間の認証で OAuth 2.0 を使用するものの、OAuth 2.0 サーバがない場合は、InterSystems IRIS for Health に用意されているユーティリティを使用できます。このユーティリティは、バルク FHIR コーディネータのエンドポイントで SMART バックエンド・サービス承認Opens in a new tabをサポートすることを主な目的として、ローカル・インスタンス上に OAuth 2.0 サーバを作成します。この OAuth サーバは、動的クライアント登録をサポートするように構成されます。
このユーティリティを適切に使用するには、以下の前提条件を満足する必要があります。
-
SSL/TLS に対応するように Web サーバを構成している。
-
使用しているインスタンスに SSL/TLS 構成を作成している。
-
インストーラ・ウィザードの [安全な通信の構成] ダイアログで、安全な通信構成を作成し、有効にしている。
-
インストーラ・ウィザードで安全な通信を構成した後、バルク FHIR 構成を作成する Foundation ネームスペースを構成し、有効にしている。
この OAuth 2.0 サーバ・ユーティリティは、HS.BulkFHIR.OAuth2InstallerOpens in a new tab クラスの 2 つのメソッドから構成されています。Foundation ネームスペースから以下のメソッドを呼び出します。
バルク FHIR のローカル IRIS インスタンスに IRIS OAuth 2.0 承認サーバを構成し、さらにその OAuth サーバの発行者エンドポイントを指すサービス・レジストリ・エントリを作成します。このメソッドでは、これら 2 つのアイテムの値がクラス・パラメータの OAuthSSLConfigName と OAuthIssuerServiceName に依存しています。
引数 :
-
pForceDelete
0 = 既存の OAuth サーバが見つかった場合は実行を中止し、失敗であることを返します (既定)。
1 = 既存の OAuth サーバとそのクライアントを削除したうえで再作成します。
-
pVerbose
0 = メソッドの実行結果テキストを表示しません。
1 = メソッドの実行結果テキストを表示します (既定)。
現在の IRIS インスタンスでの OAuth サーバの発行者エンドポイントを指すサービス・レジストリ・エントリを、現在のネームスペースに作成します。このメソッドでは、これら 2 つのアイテムの値がクラス・パラメータの OAuthSSLConfigName と OAuthIssuerServiceName に依存しています。
OAuth サーバを既に目的どおりに設定済みで、別の Foundation ネームスペースにバルク FHIR 構成を作成する場合にのみ、このメソッドが必要です。
引数 :
-
pVerbose:
0 = メソッドの実行結果テキストを表示しません。
1 = メソッドの実行結果テキストを表示します (既定)。
バルク FHIR 設定チェックリスト
バルク FHIR 相互作用の構成では、さまざまな場所で多数の移動操作が必要です。必要なすべての構成が発生していることを確認するためのチェックリストを以下に示します。この確認により、バルク FHIR 相互作用の正常な動作を図ります。
FHIR リソース・サーバ設定のチェックリスト
-
FHIR リソース・サーバごとにエンドポイントの URL を取得します。
-
SSL/TLS 構成情報を取得します。
-
OAuth 取得アダプタを使用している場合は、FHIR エンドポイントの OAuth サーバ・エンドポイントの URL を取得します。受け入れられる付与タイプを確認します。
-
ODS 取得アダプタを使用している場合は、Unified Care Record レジストリの Web サービス・エンドポイントと SSL/TLS 構成情報を取得します。
-
指定の検索で返すことができるリソースの数が FHIR エンドポイントによって制限されている場合は、検索エラーを防止するために、この制限値を大きくすることを検討します。InterSystems IRIS for Health の場合、FHIR サーバを作成すると、[検索結果の最大数] 設定が既定で 1000 に設定されます。この値を大きくするには、[ホーム]→[Health]→[FHIR 構成]→[サーバ構成]→[endpoint→[構成]→[検索結果の最大数] へ移動します。推奨値は FHIR サーバのコンテンツによって異なりますが、3000 であれば十分です。
バルク FHIR コーディネータ設定のチェックリスト
BFC 構成を作成する前に、以下の前提条件が成立していることを確認します。
SSL/TLS 構成の作成
-
各 FHIR リソース・サーバおよび各 OAuth サーバとの通信で使用する SSL/TLS 構成を作成します。
-
ODS 取得アダプタを使用している場合は、Unified Care Record Web サーバとの通信で使用する SSL/TLS 構成を作成します。
相互運用認証情報の作成
-
HTTP 取得アダプタを使用している場合は、FHIR エンドポイントへの認証のための認証情報を作成します。
-
X-API Key 取得アダプタを使用している場合は、FHIR エンドポイントへの認証のための認証情報を作成します。この場合は、API キーがこの認証情報のパスワードになります。
-
OAuth 取得アダプタを使用していて、FHIR エンドポイントの付与タイプで基本的な認証の認証情報が必要な場合は、取得トークンの認証情報を作成します。
OAuth の設定
OAuth 2.0 を BFC 承認アダプタとして使用している場合、または FHIR エンドポイントで取得に OAuth 2.0 を必要とする場合は、OAuth を適切に設定する必要があります。この設定では、BFC 向け OAuth サーバ、OAuth を必要とする FHIR エンドポイントのサーバ記述、さまざまなクライアント構成を作成することがあります。
OAuth を BFC 承認アダプタとして使用する場合は、SMART バックエンド・サービス承認Opens in a new tabをサポートするバルク FHIR コーディネータで使用する OAuth サーバの URL を指定する必要があります。OAuth サーバがない場合は、InterSystems IRIS for Health のユーティリティを使用して OAuth サーバを作成できます。
OAuth を BFC の承認アダプタとして使用する場合は、その BFC を OAuth サーバ発行者エンドポイントに対する OAuth リソース・サーバとして、その BFC の OAuth クライアント構成が必要です。そのアプリケーション名を記録しておきます。
OAuth サーバで動的クライアント登録がサポートされていれば、BFC 構成を保存するときに、OAuth クライアント構成が自動的に作成されます。
OAuth を BFC の承認アダプタとして使用する場合は、OAuth サーバ発行者エンドポイントに対する OAuth クライアント構成が、バルク FHIR REST クライアントで使用するために必要です。各クライアントのアプリケーション名とクライアント ID を記録しておきます。
このような OAuth クライアント構成が [クライアント] フィールドに挙げられていて、OAuth サーバで動的クライアント登録がサポートされていれば、BFC 構成を保存するときに、OAuth クライアント構成が自動的に作成されます。また、これらの構成を手動で作成することもできます。
承認タイプが OAuth である FHIR エンドポイントごとに、FHIR エンドポイントの OAuth サーバに対する検出を使用して、BFC インスタンスにサーバ記述を作成します。動的クライアント登録を使用するか、手動でクライアント ID とクライアントの秘密鍵を入力することで、各 FHIR エンドポイントの OAuth サーバ発行者エンドポイントに対し、BFC の OAuth クライアント構成を作成します。
FHIR エンドポイントの OAuth サーバで発見と動的クライアント登録がサポートされていれば、BFC 構成を保存するときに、そのFHIR エンドポイントの OAuth サーバ向けにサーバ記述と BFC クライアント構成の両方が自動的に作成されます。
ユーザの設定
-
%HS_BFC_Administrator ロールを持つ管理ユーザを作成します。
-
OAuth エクスポート・クライアントごとにダミー・ユーザを作成します。このダミー・ユーザには %HS_BFC_Exporter 以上のロールが必要です。また、承認済みユーザとして指定する必要があります。
各 OAuth エクスポート・クライアントには、OAuth クライアント構成および名前が同じダミー InterSystems IRIS ユーザの両方が必要です。このダミー・ユーザは、適切なロールを OAuth クライアントに対応付けます。
OAuth クライアントのダミー・ユーザを作成するには以下の手順に従います。
-
バルク FHIR コーディネータのインスタンスで、[ホーム]→[システム管理]→[セキュリティ]→[ユーザ]→[新規ユーザ作成] へ移動します。
-
認証アダプタを構成したときに [クライアント] に入力したname文字列と同じ名前を [名前] フィールドに入力します。これは、OAuth クライアント構成で指定したアプリケーション名です。
-
[パスワード] フィールドと [パスワード (再入力)] フィールドの両方に、まったく同じランダムな文字列を入力します。このアカウントをログインには使用しない場合でも、InterSystems IRIS のユーザを作成するためにパスワードが必要です。
-
このユーザ・アカウントはログインに使用しないので [ユーザ有効] の選択を解除します。これにより、誰かがユーザとしてログインすることを防止できます。
-
[保存] をクリックします。
-
[ロール] タブで適切なユーザ・ロールを追加します。一般的には %HS_BFC_Exporter を追加します。ロールを追加するには、そのロールを [利用可能] ペインで選択し、 をクリックして [選択済み] ペインへ移動します。続いて、以下のように [割り当てる] をクリックします。
このダミー・ユーザは、ユーザのロールを OAuth クライアントに対応付ける手段としてのみ使用されます。これにより、REST エクスポート・クライアントが FHIR 相互作用でこの BFC エンドポイントに接続できます。
-
ストレージの場所の設定
-
エクスポートに使用する一時作業ディレクトリを特定します。
-
エクスポートで生成される ndjson ファイルを収めるうえで十分な容量のストレージ・ディレクトリを指定します。
-
BFC 構成を保存するときに、指定したファイル URL を使用して CSP アプリが作成されます。
REST クライアント設定のチェックリスト
-
上記で説明したように、BFC エンドポイントの URL に対する動的クライアント登録を使用して、REST クライアントで使用する OAuth クライアント構成を作成します。
-
OAuth を使用している REST クライアントからバルク FHIR エクスポートを開始するとき、またはそのステータスを確認するときは、以下と共にアクセス・トークンを提示します。
-
BFC 構成の [取得] タブで特定した付与タイプ。
-
OAuth サーバのアクセス・トークン・エンドポイント (issuerEndpoint/token) と、必要に応じて対象ユーザ (?aud=https://bfcEndpoint)。
-
BFC 構成の [認証タイプ] タブに挙げられているいずれかの OAuth クライアントのクライアント ID とクライアント秘密鍵。
-
スコープ。最小限必要なスコープは system/Patient.read です。system/*.read を指定するとすべてが許可されます。
-
-
OAuth を使用している REST クライアントを使用して BFC ファイル・サーバから ndjson ファイルをダウンロードするときは、以下と共にアクセス・トークンを提示します。
-
BFC 構成の [取得] タブで特定した付与タイプ。
-
OAuth サーバのアクセス・トークン・エンドポイント (issuerEndpoint/token) と、必要に応じて対象ユーザ (?aud=https://bfcFileEndpoint)。
-
BFC 構成の [認証タイプ] タブに挙げられているいずれかの OAuth クライアントのクライアント ID とクライアント秘密鍵。
-
スコープ。ファイルのダウンロードでは一般的に user/*.read です。
-