リモートヘルプ要求 API
リモートヘルプ要求 API は、電子医療記録 (EMR) システムから IT サービス要求とその詳細のリストを作成、表示、およびフェッチするためのエンドポイントを提供します。IT サービス要求は、タスクタイプ (ServiceNow インスタンスのインシデントなど) に関連付けられます。
この API は、 EMR Help アプリケーション (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 テーブルに挿入します。
タスクのパラメーターと、タスクに関連付けられた要求データテーブルに保持される EMR システムからの追加データに加えて、要求定義 ID を指定する必要があります。2 つのタイプのデータをこのエンドポイントに渡します。1 つ目は要求データで、エンドポイントがリモート要求データ [sn_ind_rmt_help_request_data] テーブルとその関連子テーブルに挿入します。2 つ目は IT サービス要求のタスクパラメーターで、エンドポイントがリモート要求パラメーター [sn_ind_rmt_help_request_param] テーブルにこれを挿入します。要求定義で定義されたデータまたはフィールドのみがエンドポイントによって処理されます。このデータモデルの詳細については、「 EMR Help データモデル」を参照してください。
レコードは、要求定義 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 システムのリクエスト定義の設定」を参照してください。 データタイプ: オブジェクト |
| source | 必須です。要求定義で指定されたエンドポイントを呼び出す 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 | 結果オブジェクト。 データタイプ:オブジェクト
|
| result.code | result.status が failure として返された場合のアプリケーションエラーコード。 データタイプ:文字列 |
| result.error | result.status が失敗の場合に含まれるエラーメッセージ。 このメッセージは英語のみです。 データタイプ:文字列 |
| result.errorTranslated | オプションのローカライズされたエラーメッセージ。 データタイプ:文字列 |
| result.status | 応答のステータス。 有効な値:
データタイプ:文字列 |
| result.task_id | 作成されたタスクの sys_ID。 データタイプ:文字列 |
| result.task_table | 要求定義で定義されたタスクが作成されたタスクテーブルの名前。 データタイプ:文字列 |
| result.warning | オプションの警告メッセージ。result.status が success の場合に含まれることがあります。 このメッセージは英語のみです。 データタイプ:文字列 |
| 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 システムのリクエスト定義の設定」を参照してください。 データタイプ: オブジェクト |
| source | 必須です。要求定義で指定されたエンドポイントを呼び出す 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 | 結果オブジェクト。 データタイプ:オブジェクト
|
| result.code | result.status が failure として返された場合のアプリケーションエラーコード。 データタイプ:文字列 |
| result.error | result.status が失敗の場合に含まれるエラーメッセージ。 このメッセージは英語のみです。 データタイプ:文字列 |
| result.errorTranslated | オプションのローカライズされたエラーメッセージ。 データタイプ:文字列 |
| result.status | 応答のステータス。 有効な値:
データタイプ:文字列 |
| result.warning | オプションの警告メッセージ。result.status が success の場合に含まれることがあります。 このメッセージは英語のみです。 データタイプ:文字列 |
| 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 とクエリフィルターに一致するタスクのリストをフェッチします。
- 参照タイプおよび選択肢タイプのフィールドは、常に value と 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 列。 |
| 名前 | 説明 |
|---|---|
| query | 必須。結果セットのフィルタリングに使用されるエンコードされたクエリ。 データタイプ:文字列 |
| 名前 | 説明 |
|---|---|
| なし |
ヘッダー
次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「 サポートされている REST API ヘッダー」を参照してください。
| ヘッダー | 説明 |
|---|---|
| 承認 | 応答本文のデータフォーマット。application/json のみをサポートします。 |
| ヘッダー | 説明 |
|---|---|
| なし |
ステータスコード
この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。
| ステータスコード | 説明 |
|---|---|
| 200 | 成功。要求が正常に処理されました。 |
| 401 | 権限がありません。ユーザー資格情報が間違っているか、渡されていません。 |
| 500 | 内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。応答に、エラーに関する追加情報が含まれます。 |
応答本文のパラメーター (JSON)
| 名前 | 説明 |
|---|---|
| result | 返される結果: データタイプ:オブジェクト
|
| result.code | result.status が failure として返された場合のアプリケーションエラーコード。 データタイプ:文字列 |
| result.error | result.status が失敗の場合に含まれるエラーメッセージ。 このメッセージは英語のみです。 データタイプ:文字列 |
| result.errorTranslated | オプションのローカライズされたエラーメッセージ。 データタイプ:文字列 |
| result.status | 応答のステータス。 可能な値:
データタイプ:文字列 |
| result.task_list | タスクのリスト。 データタイプ:アレイ |
| result.warning | オプションの警告メッセージ。result.status が success の場合に含まれることがあります。 このメッセージは英語のみです。 データタイプ:文字列 |
| 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 で指定された単一のタスクをフェッチします。
- 参照タイプおよび選択肢タイプのフィールドは、常に value と 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 | 返される結果: データタイプ:オブジェクト
|
| result.code | result.status が failure として返された場合のアプリケーションエラーコード。 データタイプ:文字列 |
| result.error | result.status が失敗の場合に含まれるエラーメッセージ。 このメッセージは英語のみです。 データタイプ:文字列 |
| result.errorTranslated | オプションのローカライズされたエラーメッセージ。 データタイプ:文字列 |
| result.status | 応答のステータス。 可能な値:
データタイプ:文字列 |
| result.task_parameters | 必須です。IT サービス要求のタスクパラメーターを記述する名前と値のペア。オブジェクトの各要素は、インシデント [incident] テーブルなどの対応するタスクテーブルの列に対応します。 データタイプ:オブジェクト |
| result.warning | オプションの警告メッセージ。result.status が success の場合に含まれることがあります。 このメッセージは英語のみです。 データタイプ:文字列 |
| 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"
}
}