バルク FHIR コーディネータ

バルク FHIR の作成/編集ワークフロー ： 設定構成

バルク FHIR 構成を対象とした作成/編集ワークフローの [構成設定] ページには以下の各設定があります。

バルク FHIR の作成/編集ワークフロー ： 承認の構成

作成/編集ワークフローの [認証タイプ] ページに表示される設定は、選択した Auth Adapter によって異なります。

クライアント

この BFC エンドポイントからのバルク FHIR エクスポートの実行が承認されている OAuth クライアントのリスト。

[ホーム] → [システム管理] → [セキュリティ] → [OAuth 2.0] → [クライアント] → [issuerEndpoint] → [クライアント構成] で、OAuth クライアント構成と一致する OAuth クライアント記述を OAuth サーバに定義しておく必要があります。

OAuth クライアント構成ごとにアプリケーション名があります ([一般] タブに表示されています)。

この BFC 構成を使用する OAuth クライアントを指定するには、name:authentication_method 形式のコンマ区切りリストを [クライアント] フィールドに入力します。

• name は、OAuth クライアント構成にあるアプリケーション名です。

• authentication_method には、このクライアントが OAuth サーバへの認証に使用する Open ID Connect ワークフローを指定します。authentication_method の値は、client_secret_post または private_key_jwt とする必要があります。

Note:

入力したクライアント構成が存在しない場合、使用している OAuth サーバが動的クライアント登録をサポートしていれば、このバルク FHIR 構成を保存するとそのクライアント構成が自動的に作成されます。これらのクライアントを手動で作成することもできます。

各 OAuth クライアント構成には、クライアント ID とクライアントの秘密鍵も記述されています ([クライアントの認証情報] タブに表示されます)。

バルク・データ REST クライアントが BFC エンドポイントに要求を送信するとき、そのクライアントが提示したアクセス・トークンには client_id と client_secret が記述されます。アクセス・トークンの client_id は、BFC 構成の [クライアント] フィールドに示されている OAuth クライアント構成のクライアント ID との比較で検証されます。アクセス・トークンの client_secret は、OAuth クライアント構成のクライアントの秘密鍵との比較で検証されます。

Important:

各 OAuth エクスポート・クライアントには、OAuth クライアント構成および名前が同じダミー InterSystems IRIS ユーザの両方が必要です。このダミー・ユーザは、適切なロールを OAuth クライアントに対応付けます。詳しい手順は、"ユーザの設定" を参照してください。

このダミー・ユーザは、ユーザのロールを OAuth クライアントに対応付ける手段としてのみ使用されます。これにより、REST エクスポート・クライアントが FHIR 相互作用でこの BFC エンドポイントに接続できます。多くの場合、このユーザは“有効ではない”ものとして作成されるので、このユーザの認証情報を使用して実際のユーザがログインすることはできません。

バルク FHIR の作成/編集ワークフロー ： 取得の構成

作成/編集ワークフローの [Fetch] ページでは以下の手順を実行できます。

1. 取得アダプタの選択

2. 取得アダプタの構成

3. 承認設定の構成

取得の構成 ： アダプタの構成

[Adapter Configuration] 見出しに示されている設定は、ODS 取得アダプタに対してのみ表示される Registry Webservice 設定を除き、すべてが PureFHIR 取得アダプタと ODS 取得アダプタの両方に対して表示されます。

エンドポイント URL

FHIR エンドポイントの完全な URL。例えば、https://example.org/fhir/r4。このフィールドへの入力は必須です。

SSL 構成

HTTPS を使用して FHIR エンドポイントと通信する方法を記述した、InterSystems IRIS の SSL/TLS クライアント構成。

リソース・タイプ

この構成のエクスポート・オペレーションで扱う必要がある FHIR リソース・タイプをコンマ区切りで記述した既定のリスト。バルク・データ要求に _type クエリ・パラメータを使用することで、このリストをクライアントによってオーバーライドできます。このフィールドを空のままにすると、既定ですべてのリソース・タイプが扱われます。

Max Requests Per Second

FHIR エンドポイントに対して毎秒実行できる HTTP(S) 要求の最大数。この値は、構成のすべてのアクティブなエクスポート・オペレーションに共通で適用されるので、バルク FHIR コーディネータによって FHIR エンドポイントに発生する負荷を制限するために使用できます。秒あたり 10 件の要求が既定値です。

HTTP Timeout

データの取得で FHIR エンドポイントに対して実行する HTTP(S) 要求ごとのタイムアウト値 (秒)。エクスポートするデータが大量で、FHIR エンドポイントのページ・サイズが大きい場合、取得でタイムアウト・エラーが発生するのであれば、このタイムアウトを長くします。既定値は 180 秒です。

ワーカ・ジョブ

取得処理の実行が割り当てられているバックグラウンド・ワーカ・ジョブの数。4 件のジョブが既定値です。

Registry Webservice Credential Id

HS.BulkFHIR.Fetch.ODS.Adapter を使用するときは必ず指定します。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 サービスを呼び出すときは、この認証情報のユーザ名とパスワードが使用されます。

Registry Webservice Endpoint URL

HS.BulkFHIR.Fetch.ODS.Adapter を使用するときは必ず指定します。Unified Care Record レジストリの Hub Web サービス の URL。通常は、以下のとおりです。

https://UCRHost:Port/csp/healthshare/registryNamespace/services/HS.Hub.HSWS.WebServices.cls

バルク FHIR の作成/編集ワークフロー ： ストレージの構成

バルク FHIR 構成を対象とした作成/編集ワークフローの [Storage Location] ページには以下の各設定があります。

バルク FHIR の作成/編集ワークフロー ： 構成のレビューと検証

バルク FHIR 構成を対象とした作成/編集ワークフローの [レビュー] ページには、他のページにある各設定の値が表示されます。これらの設定をレビューし、[構成] をクリックしてバルク FHIR 構成を保存します。[構成] をクリックすると BFC によって各設定が検証され、対処を必要とする問題があるとそれが表示されます。各設定が検証に適合すると、必要な OAuth クライアント構成とサーバ記述が BFC によってすべて自動的に構成されます。

[構成設定] ページの JSON 例

[認証タイプ] ページの JSON 例

• 基本的な承認アダプタの JSON 例

• OAuth アダプタの JSON 例

基本的な承認アダプタ

OAuth アダプタ

[Fetch] ページの JSON 例

• ODS 取得アダプタの JSON 例

• 純粋な FHIR 取得アダプタの JSON 例

• 取得承認設定

ODS 取得アダプタ

"fetch_config": { プロパティの終了部分は、"取得承認設定" を参照してください。

純粋な FHIR 取得アダプタ

"fetch_config": { プロパティの終了部分は、"取得承認設定" を参照してください。

取得承認設定

• HTTP 取得承認の JSON 例

• X-API 取得承認の JSON 例

• OAuth 取得承認の JSON 例

HTTP 取得承認

以下の JSON フラグメントは "fetch_config": { プロパティの終了部分です。

X-API 取得承認

以下の JSON フラグメントは "fetch_config": { プロパティの終了部分です。

OAuth 取得承認

以下の JSON フラグメントは "fetch_config": { プロパティの終了部分です。

[Storage Location] ページの JSON 例

[エクスポート] ページへのアクセス

バルク FHIR エクスポートを開始または検査するには以下の手順に従います。

1. 適切な特権を持つユーザとして InterSystems IRIS for Health にログインします。

2. [ホーム] → [Health] → [foundationNamespace] → [バルク FHIR コーディネータ] に移動します。

3. 以下のいずれかの方法で [エクスポート] ページに移動します。

   • [エクスポート] リンクをクリックし、[エクスポート] → [リスト] ページを開いてすべてのエクスポートを表示します。

   • をクリックし、[エクスポート] → [表示] ページを開いて特定の構成のエクスポートを表示します。

[エクスポート] ページでは、進行中のエクスポートと完了したエクスポートのステータスを確認できます。以下の各アクションも実行できます。

アイコン	アクション	注
	新規エクスポート要求	新規エクスポートを開始します。
	一時停止	進行中のエクスポートを一時停止します。
	再開	一時停止していたエクスポートを再開します。
	キャンセル	進行中のエクスポートをキャンセルします。
	ログの表示	進行中のエクスポートまたは完了したエクスポートのログを表示します。[ログ] → [リスト] ページを開き、エクスポート・ログをフィルタ処理して表示できます。
	コピー	完了したエクスポートの情報を使用して新しいエクスポートを作成します。
	ダウンロード	[エクスポート] → [Exported Files] ページを開きます。タイプ別に特定リソースの ndjson ファイルを検索してダウンロードできるほか、エクスポート・エラーもダウンロードできます。

エクスポート要求の開始

1. [エクスポート] ページで [New Export Request] をクリックしてエクスポートを開始します。

2. [構成] ドロップダウン・リストから BFC 構成を選択します。

3. [次へ] をクリックします。

4. [エクスポート] からエクスポートのタイプを選択します。[システム]、[グループ]、または [患者] を選択できます。

5. グループのエクスポートを選択した場合は、[Group ID] にグループ ID を入力します。Unified Care Report ODS では、コホート名がグループ ID になります。

6. 必要に応じ、[Since] フィールドに YYYY-MM-DD の書式で日付を入力するか、日付選択機能を使用して日付を選択します。[Add Time] をクリックして時刻を入力することもできます。

7. [Export Now] をクリックするとエクスポートが始まります。

8. [エクスポート] ページの [処理中] テーブルにエクスポートが行として表示されます。進行中のエクスポートを一時停止、再開、またはキャンセルできます。ログを表示して、エクスポートの進行状況を確認することもできます。

完了したエクスポートの ndjson のダウンロード

1. [エクスポート] ページの [Completed Exports] ペインで必要に応じてフィルタ値を入力し、[適用] をクリックすると完了済みエクスポートのリストがフィルタ処理されます。

2. [Completed Exports] テーブルの目的の行で をクリックすると、そのエクスポートに存在するファイルの一覧が表示されます。エクスポートするファイルがリソース・タイプ別に分類されています。

3. 一覧に表示されるファイルを少なくするには、必要に応じて検索語を入力します。

4. ndjson ファイルをダウンロードするには をクリックします。

エクスポート・ログの表示

バルク FHIR ワークフローの以下のコンポーネントで発生した各種イベントについて、エクスポート・ログに詳しい情報が記録されます。

セッションのエクスポート・ログを表示するには以下の手順に従います。

1. [エクスポート] ページで、[処理中] または [完了] が示されたセッションの行で をクリックします。または、[ログ] をクリックしてすべてのセッションのログを表示します。

2. 必要に応じ、一覧に表示されるログを少なくするには、フィルタ値を入力して [適用] をクリックします。

3. をクリックすると特定のログ・ファイルが表示されます。

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 では、以下のオプション・パラメータを使用できます。

REST クライアントからのエクスポートのステータス確認

最初の GET 要求に対する応答ヘッダには、以下の形式で URL を指定した CONTENT-LOCATION キーがあります。

bfcEndpoint/status/sessionNumber

CONTENT-LOCATION の URL へ定期的に GET 要求を送信して、バルク FHIR エクスポート・セッションのステータスを取得します。

以下のようなステータス応答が返されます。

完了したエクスポートの ndjson のダウンロード

受信した応答ヘッダに Status: 200 OK があれば、BFC ファイル・サーバから目的のファイルをダウンロードできます。これらのファイルを取得するには、ファイルの URL ごとに GET 要求を送信します。

この BFC 構成で OAuth の Auth アダプタを使用している場合は、以下を指定して新しいアクセス・トークンを取得します。

• BFC 構成の [取得] タブで特定した付与タイプ。

• OAuth サーバのアクセス・トークン・エンドポイント ：

  issuerEndpoint/token
  

  

  必要に応じて対象ユーザ ：

  ?aud=https://bfcFileEndpoint
  

  

• BFC 構成の [認証タイプ] タブに挙げられているいずれかの OAuth クライアントのクライアント ID とクライアント秘密鍵。

• スコープ。ファイルのダウンロードでは一般的に user/*.read です。

以下に例を示します。

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 構成の作成

• 相互運用認証情報の作成

• OAuth の設定

• ユーザの設定

• ストレージの場所の設定

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 です。