リモートヘルプ要求 API
リモートヘルプ要求 API は、電子医療記録 (EMR) システムから IT サービス要求とその詳細のリストを作成、表示、およびフェッチするためのエンドポイントを提供します。IT サービス要求は、 ServiceNow インスタンス内のインシデントなどのタスクタイプに関連付けられています。
この API は、 EMR ヘルプ アプリケーション (sn_ind_rmt_help) が ServiceNow Store からインストールされます。 ServiceNow Store Web サイトにアクセスして利用可能なすべてのアプリを表示し、ストアにリクエストを送信する方法について確認してください。リリースされたすべてのアプリのリリースノート情報については、「ServiceNow Storeバージョン履歴のリリースノート」を参照してください。
この API のエンドポイントにアクセスするために必要なロール:sn_ind_rmt_help.requester。
リモートヘルプ要求 :POST /remote_help_request/{req_defn_id}
電子医療記録 (EMR) システムデータを対応する ServiceNow テーブルに挿入します。
タスクのパラメーターに加えて、 要求定義 ID と、タスクに関連付けられた要求データテーブルに保持される EMR システム からの追加データを指定する必要があります。このエンドポイントには 2 つのタイプのデータを渡します。1 つ目は要求データで、エンドポイントがリモート要求データ [sn_ind_rmt_help_request_data] テーブルとそれに関連する子テーブルに挿入します。2 つ目は、IT サービス要求のタスクパラメーターで、エンドポイントがリモート要求パラメーター [sn_ind_rmt_help_request_param] テーブルに挿入します。要求定義で定義されたデータまたはフィールドのみがエンドポイントによって処理されます。このデータモデルの詳細については、「 EMR ヘルプデータモデル」を参照してください。
レコードは、要求定義 ID を使用して識別されます。
URL 形式
バージョニングされた URL: /api/sn_ind_rmt_help/{api_version}/remote_help_request/{req_defn_id}
デフォルト URL: /api/sn_ind_rmt_help/remote_help_request/{req_defn_id}
サポートされている要求パラメーター
| 名前 | 説明 |
|---|---|
| api_version | オプション。アクセスするエンドポイントのバージョン。たとえば、 v1 や v2 などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。 データタイプ:文字列 |
| req_defn_id | 要求定義の一意の ID。 データタイプ:文字列 テーブル:リモート要求定義 [sn_ind_rmt_help_request_defn] テーブルの [ID] 列にあります。 |
| 名前 | 説明 |
|---|---|
| なし |
| 名前 | 説明 |
|---|---|
| request_data | 必須。リモート要求データ [sn_ind_rmt_help_request_data] テーブルとその子テーブルに追加する、 EMR システム からの要求データの名前と値のペア。 たとえば、次のようになります: 注: request_data オブジェクトの要求定義で構成されたパラメーターのみを渡します。その他のパラメーターは無視されます。詳細については、「 EMR システムの要求定義の構成」を参照してください。 データタイプ:オブジェクト |
| ソース | 必須。要求定義で指定されたエンドポイントを呼び出す EMR システムの名前。 たとえば、次のようになります: データタイプ:文字列 |
| task_parameters | 必須。IT サービス要求のタスクパラメーターを説明する名前と値のペア。オブジェクト内の各要素は、インシデント [incident] テーブルなどの対応するタスクテーブルの列に対応します。 たとえば、次のようになります: 注: task_parameters オブジェクトの要求定義で構成されたパラメーターのみを渡します。その他のパラメーターは無視されます。詳細については、「 EMR システムの要求定義の構成」を参照してください。 データタイプ:オブジェクト |
ヘッダー
次の要求ヘッダーと応答ヘッダーは、この HTTP アクションにのみ適用されるか、別の方法でこのアクションに適用されます。REST API で使用される一般的なヘッダーのリストについては、「 サポートされている REST API ヘッダー」を参照してください。
| ヘッダー | 説明 |
|---|---|
| 受容 | 応答本文のデータ形式。application/jsonのみをサポートしています。 |
| Content-Type | 要求本文のデータ形式。application/jsonのみをサポートしています。 |
| ヘッダー | 説明 |
|---|---|
| なし |
ステータスコード
この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。
| ステータスコード | 説明 |
|---|---|
| 200 | 成功。要求が正常に処理されました。 |
| 401 | 権限がありません。ユーザー認証情報が正しくないか、渡されていません。 |
| 500 | 内部サーバーエラー要求の処理中に予期しないエラーが発生しました。応答には、エラーに関する追加情報が含まれています。 |
応答本文のパラメーター (JSON)
| 名前 | 説明 |
|---|---|
| 結果 | 結果オブジェクト。 データタイプ:オブジェクト
|
| result.code | result.statusが失敗として返された場合のアプリケーションエラーコード。 データタイプ:文字列 |
| result.error | result.statusが失敗した場合に含まれるエラーメッセージ。 このメッセージは英語のみです。 データタイプ:文字列 |
| result.errorTranslated | オプションのローカライズされたエラーメッセージ。 データタイプ:文字列 |
| result.status | 応答のステータス。 有効な値:
データタイプ:文字列 |
| result.task_id | 作成されたタスクのSys_id。 データタイプ:文字列 |
| result.task_table | 要求定義での定義に従ってタスクが作成されたタスクテーブルの名前。 データタイプ:文字列 |
| result.warning | オプションの警告メッセージ。result.statusが成功した場合に含まれることがあります。 このメッセージは英語のみです。 データタイプ:文字列 |
| result.warningTranslated | オプションのローカライズされた警告メッセージ。 データタイプ:文字列 |
cURL 要求
Cerner EMR システムからデータを挿入します。
curl "https://instance.servicenow.com/api/sn_ind_rmt_help/v1/remote_help_request/sn_it_request"
--request POST \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data "{
"source":"Cerner",
"task_parameters":{
"short_description":"Unable to load patient data",
"caller_id":"82d4ecb4db40e8100e28aa594b96195c",
"impact":"2",
"contact_type":"email"
},
"request_data":{
"application":"Powerchart",
"server":"CTXCHSITN453",
"environment":"CTX24",
"issue_type":"Helpdesk",
"millennium_username":"JOHN JASON",
"position":"Lab Tech",
"session_recording_id":"s5ds34dd96491b959a35010651896k",
"user_is_physician":"Yes",
"work_station":"PC354FLR3STATION7",
"additional_info":"MRN 222333"
}
}" \
--user "username":"password"
次の出力は、成功した応答とエラー応答の両方を示しています。
// Successful response
{
"result": {
"task_id": "75b09061db2cac100e28aa594b9619fa",
"status": "success",
"task_table": "incident",
"warning": "Ignored invalid fields on table incident : test1",
"warningTranslated": "Ignored invalid fields on table incident : test1"
}
}
// Error response
{
"result": {
"status": "failure",
"code": "1001",
"error": "Invalid request definition: test_request1",
"errorTranslated": "Invalid request definition: test_request1"
}
}
リモートヘルプ要求 :PUT /remote_help_request/{req_defn_id/task/{task_id}
タスクの指定されたリモート要求データテーブルのレコードを更新します。
以前に作成されたリモート要求を更新するためのタスクsys_idに加えて、要求定義 ID を指定できます。
URL 形式
バージョニングされた URL: /api/sn_ind_rmt_help/{api_version}/remote_help_request/{req_defn_id/task/{task_id}
デフォルト URL: /api/sn_ind_rmt_help/remote_help_request/{req_defn_id/task/{task_id}
サポートされている要求パラメーター
| 名前 | 説明 |
|---|---|
| api_version | オプション。アクセスするエンドポイントのバージョン。たとえば、 v1 や v2 などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。 データタイプ:文字列 |
| req_defn_id | 要求定義の一意の ID。 データタイプ:文字列 テーブル:リモート要求定義 [sn_ind_rmt_help_request_defn] テーブルの [ID] 列にあります。 |
| task_id | 更新するタスクのSys_id。このフィールドは、EMR システムによって提供されます。 データタイプ:文字列 |
| 名前 | 説明 |
|---|---|
| なし |
| 名前 | 説明 |
|---|---|
| request_data | 必須。リモート要求データ [sn_ind_rmt_help_request_data] テーブルまたはその子テーブルを更新するための EMR システム からの要求データの名前と値のペア。 たとえば、次のようになります: 注: request_data オブジェクトの要求定義で構成されたパラメーターのみを渡します。その他のパラメーターは無視されます。詳細については、「 EMR システムの要求定義の構成」を参照してください。 データタイプ:オブジェクト |
| ソース | 必須。要求定義で指定されたエンドポイントを呼び出す EMR システムの名前。 たとえば、次のようになります: データタイプ:文字列 |
| task_parameters | 必須。IT サービス要求のタスクパラメーターを説明する名前と値のペア。オブジェクト内の各要素は、インシデント [incident] テーブルなどの対応するタスクテーブルの列に対応します。 たとえば、次のようになります: 注: task_parameters オブジェクトの要求定義で構成されたパラメーターのみを渡します。その他のパラメーターは無視されます。詳細については、「 EMR システムの要求定義の構成」を参照してください。 データタイプ:オブジェクト |
ヘッダー
次の要求ヘッダーと応答ヘッダーは、この HTTP アクションにのみ適用されるか、別の方法でこのアクションに適用されます。REST API で使用される一般的なヘッダーのリストについては、「 サポートされている REST API ヘッダー」を参照してください。
| ヘッダー | 説明 |
|---|---|
| 受容 | 応答本文のデータ形式。application/jsonのみをサポートしています。 |
| Content-Type | 要求本文のデータ形式。application/jsonのみをサポートしています。 |
| ヘッダー | 説明 |
|---|---|
| なし |
ステータスコード
この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。
| ステータスコード | 説明 |
|---|---|
| 200 | 成功。要求が正常に処理されました。 |
| 401 | 権限がありません。ユーザー認証情報が正しくないか、渡されていません。 |
| 500 | 内部サーバーエラー要求の処理中に予期しないエラーが発生しました。応答には、エラーに関する追加情報が含まれています。 |
応答本文のパラメーター (JSON)
| 名前 | 説明 |
|---|---|
| 結果 | 結果オブジェクト。 データタイプ:オブジェクト
|
| result.code | result.statusが失敗として返された場合のアプリケーションエラーコード。 データタイプ:文字列 |
| result.error | result.statusが失敗した場合に含まれるエラーメッセージ。 このメッセージは英語のみです。 データタイプ:文字列 |
| result.errorTranslated | オプションのローカライズされたエラーメッセージ。 データタイプ:文字列 |
| result.status | 応答のステータス。 有効な値:
データタイプ:文字列 |
| result.warning | オプションの警告メッセージ。result.statusが成功した場合に含まれることがあります。 このメッセージは英語のみです。 データタイプ:文字列 |
| result.warningTranslated | オプションのローカライズされた警告メッセージ。 データタイプ:文字列 |
cURL 要求
以前に Cerner EMR システムで作成した IT サービス要求の更新
curl "https://instance.servicenow.com/api/sn_ind_rmt_help/v1/remote_help_request/sn_it_request/task/207e57c1db60a410f50fdc5b4b96192e"
--request PUT \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data "{
"source":"Cerner",
"task_parameters":{
"impact":"1",
"contact_type":"phone"
},
"request_data":{
"additional_info" : "Please contact my office for more information."
}
}" \
--user "username":"password"
次の出力は、成功した応答とエラー応答の両方を示しています。
// Successful response
{
"result": {
"status": "success"
}
}
// Error response
{
{
"result": {
"status": "failure",
"code": "1018",
"error": "Record with sys_id 207e57js1db60a410f50fdc5b4b96192e does not exist in table incident",
"errorTranslated": "Record with sys_id 207e57js1db60a410f50fdc5b4b96192e incident does not exist in table incident"
}
}
}
リモートヘルプ要求 :GET /remote_help_request/{req_defn_id}
指定された ID とクエリフィルターに一致するタスクのリストをフェッチします。
- 参照タイプフィールドと選択肢タイプフィールドは、常に値とdisplay_valueを持つ JSON オブジェクトとして返されます。
- DateTime フィールドは文字列として返され、常に UTC で返されます。
URL 形式
バージョニングされた URL: /api/sn_ind_rmt_help/{api_version}/remote_help_request/{req_defn_id}
デフォルト URL: /api/sn_ind_rmt_help/remote_help_request/{req_defn_id}
サポートされている要求パラメーター
| 名前 | 説明 |
|---|---|
| api_version | オプション。アクセスするエンドポイントのバージョン。たとえば、 v1 や v2 などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。 データタイプ:文字列 |
| req_defn_id | 更新する要求定義の一意の ID。 データタイプ:文字列 テーブル:リモート要求定義 [sn_ind_rmt_help_request_defn] テーブルの [ID] 列にあります。 |
| 名前 | 説明 |
|---|---|
| クエリ | 必須。結果セットのフィルタリングに使用されるエンコードクエリ。 データタイプ:文字列 |
| 名前 | 説明 |
|---|---|
| なし |
ヘッダー
次の要求ヘッダーと応答ヘッダーは、この HTTP アクションにのみ適用されるか、別の方法でこのアクションに適用されます。REST API で使用される一般的なヘッダーのリストについては、「 サポートされている REST API ヘッダー」を参照してください。
| ヘッダー | 説明 |
|---|---|
| 受容 | 応答本文のデータ形式。application/jsonのみをサポートしています。 |
| ヘッダー | 説明 |
|---|---|
| なし |
ステータスコード
この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。
| ステータスコード | 説明 |
|---|---|
| 200 | 成功。要求が正常に処理されました。 |
| 401 | 権限がありません。ユーザー認証情報が正しくないか、渡されていません。 |
| 500 | 内部サーバーエラー要求の処理中に予期しないエラーが発生しました。応答には、エラーに関する追加情報が含まれています。 |
応答本文のパラメーター (JSON)
| 名前 | 説明 |
|---|---|
| 結果 | 結果を返します。 データタイプ:オブジェクト
|
| result.code | result.statusが失敗として返された場合のアプリケーションエラーコード。 データタイプ:文字列 |
| result.error | result.statusが失敗した場合に含まれるエラーメッセージ。 このメッセージは英語のみです。 データタイプ:文字列 |
| result.errorTranslated | オプションのローカライズされたエラーメッセージ。 データタイプ:文字列 |
| result.status | 応答のステータス。 可能な値:
データタイプ:文字列 |
| result.task_list | タスクのリスト。 データタイプ:アレイ |
| result.warning | オプションの警告メッセージ。result.statusが成功した場合に含まれることがあります。 このメッセージは英語のみです。 データタイプ:文字列 |
| result.warningTranslated | オプションのローカライズされた警告メッセージ。 データタイプ:文字列 |
cURL 要求
Cerner EMR システムからデータをフェッチ
curl "https://instance.servicenow.com/api/remote_help_request/v1/sn_it_request/?query=active=true" \
--header "Accept: application/json" \
--header "Content-Type: application/json"
{
"source":"Cerner",
} \
--user "username":"password"
次の出力は、成功した応答とエラー応答の両方を示しています。
// Successful response
{
"result": {
"status": "success",
"task_list": [
{
"number": "INC0010096",
"short_description": "Unable to load data - 1",
"assigned_to": {
"value": "7a381da2dbfb5410f50fdc5b4b9619f2",
"display_value": "Abel Tuter (IT agent)"
},
"opened_at": "2020-11-16 18:37:57",
"closed_at": "",
"closed_by": {},
"state": {
"value": "2",
"display_value": "In Progress"
},
"priority": {
"value": "5",
"display_value": "5 - Planning"
},
"resolved_at": "",
"resolved_by": {},
"task_id": "207e57c1db60a410f50fdc5b4b96192e"
},
{
"number": "INC0010095",
"short_description": "Application freezes intermittently 3",
"assigned_to": {},
"opened_at": "2020-11-16 18:32:05",
"closed_at": "",
"closed_by": {},
"state": {
"value": "1",
"display_value": "New"
},
"priority": {
"value": "5",
"display_value": "5 - Planning"
},
"resolved_at": "",
"resolved_by": {},
"task_id": "561d1f8ddb20a410f50fdc5b4b9619da"
}
]
}
}
// Error response
{
"result": {
"status": "failure",
"code": "1019",
"error": "Invalid query in the request for table incident",
"errorTranslated": "Invalid query in the request for table incident"
}
リモートヘルプ要求 :GET /remote_help_request/{req_defn_id}/task/{task_id}
task_idで指定された単一のタスクをフェッチします。
- 参照タイプフィールドと選択肢タイプフィールドは、常に値とdisplay_valueを持つ JSON オブジェクトとして返されます。
- DateTime フィールドは文字列として返され、常に UTC で返されます。
- ジャーナルタイプフィールドでは、追加のコメントのみがサポートされています。
- 追加のコメントは、オブジェクトの JSON アレイとして返されます。各オブジェクトは、 created_on、 created_by、および value フィールドを持つコメントを表します。最新のコメントが最初に送信されます。
URL 形式
バージョニングされた URL: /api/sn_ind_rmt_help/{api_version}/remote_help_request/{req_defn_id}/task/{task_id}
デフォルト URL: /api/sn_ind_rmt_help/remote_help_request/{req_defn_id}/task/{task_id}
サポートされている要求パラメーター
| 名前 | 説明 |
|---|---|
| api_version | オプション。アクセスするエンドポイントのバージョン。たとえば、 v1 や v2 などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。 データタイプ:文字列 |
| req_defn_id | 要求定義の一意の ID。 データタイプ:文字列 テーブル:リモート要求定義 [sn_ind_rmt_help_request_defn] テーブルの [ID] 列にあります。 |
| task_id | 返されるタスクのSys_id。このフィールドは、EMR システムによって提供されます。 データタイプ:文字列 |
| 名前 | 説明 |
|---|---|
| なし |
| 名前 | 説明 |
|---|---|
| なし |
ヘッダー
次の要求ヘッダーと応答ヘッダーは、この HTTP アクションにのみ適用されるか、別の方法でこのアクションに適用されます。REST API で使用される一般的なヘッダーのリストについては、「 サポートされている REST API ヘッダー」を参照してください。
| ヘッダー | 説明 |
|---|---|
| 受容 | 応答本文のデータ形式。application/jsonのみをサポートしています。 |
| ヘッダー | 説明 |
|---|---|
| なし |
ステータスコード
この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。
| ステータスコード | 説明 |
|---|---|
| 200 | 成功。要求が正常に処理されました。 |
| 401 | 権限がありません。ユーザー認証情報が正しくないか、渡されていません。 |
| 500 | 内部サーバーエラー要求の処理中に予期しないエラーが発生しました。応答には、エラーに関する追加情報が含まれています。 |
応答本文のパラメーター (JSON)
| 名前 | 説明 |
|---|---|
| 結果 | 結果を返します。 データタイプ:オブジェクト
|
| result.code | result.statusが失敗として返された場合のアプリケーションエラーコード。 データタイプ:文字列 |
| result.error | result.statusが失敗した場合に含まれるエラーメッセージ。 このメッセージは英語のみです。 データタイプ:文字列 |
| result.errorTranslated | オプションのローカライズされたエラーメッセージ。 データタイプ:文字列 |
| result.status | 応答のステータス。 可能な値:
データタイプ:文字列 |
| result.task_parameters | 必須。IT サービス要求のタスクパラメーターを説明する名前と値のペア。オブジェクト内の各要素は、インシデント [incident] テーブルなどの対応するタスクテーブルの列に対応します。 データタイプ:オブジェクト |
| result.warning | オプションの警告メッセージ。result.statusが成功した場合に含まれることがあります。 このメッセージは英語のみです。 データタイプ:文字列 |
| result.warningTranslated | オプションのローカライズされた警告メッセージ。 データタイプ:文字列 |
cURL 要求
Cerner EMR システムからデータをフェッチ
curl "https://instance.servicenow.com/api/sn_ind_rmt_help/v1/remote_help_request/sn_it_request/task/207e57c1db60a410f50fdc5b4b96192e"\
--request GET \
--header "Accept: application/json"\
--user "username":"password"
次の出力は、成功した応答とエラー応答の両方を示しています。
// Successful response
{
"result": {
"status": "success",
"task_parameters": {
"number": "INC0010096",
"short_description": "Unable to load data - 1",
"state": {
"value": "2",
"display_value": "In Progress"
},
"assigned_to": {
"value": "7a381da2dbfb5410f50fdc5b4b9619f2",
"display_value": "Abel Tuter (IT agent)"
},
"priority": {
"value": "5",
"display_value": "5 - Planning"
},
"caller_id": {
"value": "82d4ecb4db40e8100e28aa594b96195c",
"display_value": "Abel Tuter Requester"
},
"opened_at": "2020-11-16 18:37:57",
"closed_at": "",
"closed_by": {},
"description": "",
"impact": {
"value": "1",
"display_value": "1 - High"
},
"opened_by": {
"value": "82d4ecb4db40e8100e28aa594b96195c",
"display_value": "Abel Tuter Requester"
},
"close_code": {},
"close_notes": "",
"urgency": {
"value": "3",
"display_value": "3 - Low"
},
"category": {
"value": "inquiry",
"display_value": "Inquiry / Help"
},
"resolved_at": "",
"resolved_by": {},
"comments": [
{
"created_on": "2020-11-17 18:20:04",
"created_by": "Abel Tuter Requester",
"value": "You can reach me during office hours."
},
{
"created_on": "2020-11-16 18:40:14",
"created_by": "Abel Tuter Requester",
"value": "You can reach me during office hours."
},
{
"created_on": "2020-11-16 18:38:29",
"created_by": "Abel Tuter",
"value": "Hello there\rName of app please"
}],
"task_id": "207e57c1db60a410f50fdc5b4b96192e"
}
}
}
// Error response
{
"result": {
"status": "failure",
"code": "1001",
"error": "Invalid request definition: test_request2",
"errorTranslated": "Invalid request definition: test_request2"
}
}