Remote help request API

  • 릴리스 버전: Australia
  • 업데이트 날짜 2026년 03월 12일
  • 소요 시간: 38분

    • The Remote help request API provides endpoints to create, view, and fetch lists of IT service requests and their details from an electronic medical record (EMR) system. An IT service request is associated with a task type such as an incident in the ServiceNow instance.

    You can only use this API when the EMR Help application (sn_ind_rmt_help) is installed from the ServiceNow Store. Visit the ServiceNow Store to view all the available apps, and for information about submitting requests to the store. For cumulative release notes information for all released apps, see the ServiceNow Store version history release notes.

    Role required to access the endpoints of this API: sn_ind_rmt_help.requester.

    Remote help request - POST /remote_help_request/{req_defn_id}

    Inserts electronic medical record (EMR) system data into the corresponding ServiceNow tables.

    You need to specify a request definition ID in addition to the parameters for the task and additional data from the EMR system persisted in the request data table associated with the task. You pass two types of data into this endpoint. The first is the request data, which the endpoint inserts into the Remote Request Data [sn_ind_rmt_help_request_data] table and its associated child tables. The second is the task parameters of the IT service request, which the endpoint inserts into the Remote Request Parameter [sn_ind_rmt_help_request_param] table. Only data or fields that are defined in the request definitions are processed by the endpoint. For additional information on this data model, see EMR Help data model.

    Records are identified using the request definition ID.

    URL format

    Versioned URL: /api/sn_ind_rmt_help/{api_version}/remote_help_request/{req_defn_id}

    Default URL: /api/sn_ind_rmt_help/remote_help_request/{req_defn_id}

    주:
    Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

    Supported request parameters

    표 1. Path parameters
    Name Description
    api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

    Data type: String
    req_defn_id Unique ID of the request definition.

    Data type: String

    Table: In the ID column of the Remote Request Definition [sn_ind_rmt_help_request_defn] table.
    표 2. Query parameters
    Name Description
    None
    표 3. Request body parameters (JSON)
    Name Description
    request_data Required. Name-value pairs of the request data from the EMR system to add in the Remote Request Data [sn_ind_rmt_help_request_data] table and its child tables.

    For example:

    "request_data":{
  "additional_info": "String",
  "application": "String",
  "environment": "String",
  "issue_type": "String",
  "millennium_username": "String",
  "position": "String",
  "server": "String",
  "session_recording_id": "String",
  "user_is_physician": "String",
  "work_station": "String"
}
    주:
    Only pass parameters configured in a request definition in the request_data object. Any other parameters are ignored. To learn more, see Configure request definitions for EMR systems.

    Data type: Object
    source Required. Name of the EMR system invoking the endpoint as specified in a request definition.

    For example:

    "source":"Cerner"

    Data type: String
    task_parameters Required. Name-value pairs that describe the task parameters of the IT service request. Each element in the object corresponds to a column in the corresponding task tables such as the Incident [incident] table.

    For example:

    "task_parameters": {
  "caller_id": "String",
  "contact_type": "String",
  "impact": "String",
  "short_description": "String"
}
    주:
    Only pass parameters configured in a request definition in the task_parameters object. Any other parameters are ignored. To learn more, see Configure request definitions for EMR systems.

    Data type: Object

    Headers

    The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

    표 4. Request headers
    Header Description
    Accept Data format of the response body. Only supports application/json.
    Content-Type Data format of the request body. Only supports application/json.
    표 5. Response headers
    Header Description
    None

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    표 6. Status codes
    Status code Description
    200 Successful. The request was successfully processed.
    401 Unauthorized. The user credentials are incorrect or have not been passed.
    500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

    Response body parameters (JSON)

    Name Description
    result Result object.

    Data type: Object

    "result": {
  "code": "String",
  "error": "String",  
  "errorTranslated": "String",
  "status": "String",
  "task_id": "String",
  "task_table": "String",
  "warning": "String",
  "warningTranslated": "String"
}
    result.code Application error code when the result.status is returned as failure.

    Data type: String
    result.error Error message that is included if the result.status is failure.

    This message is in English only.

    Data type: String
    result.errorTranslated Optional localized error message.

    Data type: String
    result.status Status of the response.
    Valid values:
    • failure
    • success

    Data type: String
    result.task_id Sys_id of the created task.

    Data type: String
    result.task_table Name of the task table in which the task was created as defined in the request definition.

    Data type: String
    result.warning Optional warning message. May be included if the result.status is success.

    This message is in English only.

    Data type: String
    result.warningTranslated Optional localized warning message.

    Data type: String

    cURL request

    Insert data from a Cerner EMR system.

    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"

    The following output shows both a successful response and an error response.

    // 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"
      }
      }

    Remote help request - PUT /remote_help_request/{req_defn_id/task/{task_id}

    Updates a record in the specified remote request data table for the task.

    Enables you to specify a request definition ID in addition to the task sys_id to update a remote request that was created earlier.

    URL format

    Versioned URL: /api/sn_ind_rmt_help/{api_version}/remote_help_request/{req_defn_id/task/{task_id}

    Default URL: /api/sn_ind_rmt_help/remote_help_request/{req_defn_id/task/{task_id}

    주:
    Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

    Supported request parameters

    표 7. Path parameters
    Name Description
    api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

    Data type: String
    req_defn_id Unique ID of the request definition.

    Data type: String

    Table: In the ID column of the Remote Request Definition [sn_ind_rmt_help_request_defn] table.
    task_id Sys_id of the task to update. This field is provided by the EMR system.

    Data type: String
    표 8. Query parameters
    Name Description
    None
    표 9. Request body parameters (JSON)
    Name Description
    request_data Required. Name-value pairs of the request data from the EMR system to update the Remote Request Data [sn_ind_rmt_help_request_data] table or its child table.

    For example:

    "request_data": {
 "additional_info" : "Please contact my office for more information."
}
    주:
    Only pass parameters configured in a request definition in the request_data object. Any other parameters are ignored. To learn more, see Configure request definitions for EMR systems.

    Data type: Object
    source Required. Name of the EMR system invoking the endpoint as specified in a request definition.

    For example:

    "source":"Cerner"

    Data type: String
    task_parameters Required. Name-value pairs that describe the task parameters of the IT service request. Each element in the object corresponds to a column in the corresponding task tables such as the Incident [incident] table.

    For example:

    "task_parameters": {
  "impact":"1",
  "contact_type":"phone"
}
    주:
    Only pass parameters configured in a request definition in the task_parameters object. Any other parameters are ignored. To learn more, see Configure request definitions for EMR systems.

    Data type: Object

    Headers

    The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

    표 10. Request headers
    Header Description
    Accept Data format of the response body. Only supports application/json.
    Content-Type Data format of the request body. Only supports application/json.
    표 11. Response headers
    Header Description
    None

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    표 12. Status codes
    Status code Description
    200 Successful. The request was successfully processed.
    401 Unauthorized. The user credentials are incorrect or have not been passed.
    500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

    Response body parameters (JSON)

    Name Description
    result Result object.

    Data type: Object

    "result": {
  "code": "String",
  "error": "String",  
  "errorTranslated": "String",
  "status": "String",
  "warning": "String",
  "warningTranslated": "String"
}
    result.code Application error code when the result.status is returned as failure.

    Data type: String
    result.error Error message that is included if the result.status is failure.

    This message is in English only.

    Data type: String
    result.errorTranslated Optional localized error message.

    Data type: String
    result.status Status of the response.
    Valid values:
    • failure
    • success

    Data type: String
    result.warning Optional warning message. May be included if the result.status is success.

    This message is in English only.

    Data type: String
    result.warningTranslated Optional localized warning message.

    Data type: String

    cURL request

    Update an IT service request created earlier in a Cerner EMR system

    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"

    The following output shows both a successful response and an error response.

    // 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"
      }
      }
      }

    Remote help request - GET /remote_help_request/{req_defn_id}

    Fetches a list of tasks that match the specified ID and query filter.

    주:
    • Reference and choice type fields are always returned as JSON objects with the value and display_value.
    • DateTime fields are returned as strings and always in UTC.

    URL format

    Versioned URL: /api/sn_ind_rmt_help/{api_version}/remote_help_request/{req_defn_id}

    Default URL: /api/sn_ind_rmt_help/remote_help_request/{req_defn_id}

    주:
    Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

    Supported request parameters

    표 13. Path parameters
    Name Description
    api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

    Data type: String
    req_defn_id Unique ID of the request definition to update.

    Data type: String

    Table: In the ID column of the Remote Request Definition [sn_ind_rmt_help_request_defn] table.
    표 14. Query parameters
    Name Description
    query Required. Encoded query used to filter the result set.

    Data type: String
    표 15. Request body parameters
    Name Description
    None

    Headers

    The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

    표 16. Request headers
    Header Description
    Accept Data format of the response body. Only supports application/json.
    표 17. Response headers
    Header Description
    None

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    표 18. Status codes
    Status code Description
    200 Successful. The request was successfully processed.
    401 Unauthorized. The user credentials are incorrect or have not been passed.
    500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

    Response body parameters (JSON)

    Name Description
    result Return results.

    Data type: Object

    "result": {
  "code": "String",
  "error": "String",  
  "errorTranslated": "String",
  "status": "String",
  "task_list": [Array],
  "warning": "String",
  "warningTranslated": "String"
}
    result.code Application error code when the result.status is returned as failure.

    Data type: String
    result.error Error message that is included if the result.status is failure.

    This message is in English only.

    Data type: String
    result.errorTranslated Optional localized error message.

    Data type: String
    result.status Status of the response.
    Possible values:
    • failure
    • success

    Data type: String
    result.task_list List of tasks.

    Data type: Array
    result.warning Optional warning message. May be included if the result.status is success.

    This message is in English only.

    Data type: String
    result.warningTranslated Optional localized warning message.

    Data type: String

    cURL request

    Fetch data from a Cerner EMR system

    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"

    The following output shows both a successful response and an error response.

    // 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"
}

    Remote help request - GET /remote_help_request/{req_defn_id}/task/{task_id}

    Fetches a single task as specified in the task_id.

    Enables you to specify a request definition ID and task ID and retrieve the task details.
    주:
    • Reference and choice type fields are always returned as JSON objects with the value and display_value.
    • DateTime fields are returned as strings and always in UTC.
    • Only additional comments are supported in journal type fields.
    • Additional comments are passed back as a JSON array of objects. Each object represents a comment with created_on, created_by, and value fields. The latest comments are sent first.

    URL format

    Versioned URL: /api/sn_ind_rmt_help/{api_version}/remote_help_request/{req_defn_id}/task/{task_id}

    Default URL: /api/sn_ind_rmt_help/remote_help_request/{req_defn_id}/task/{task_id}

    주:
    Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

    Supported request parameters

    표 19. Path parameters
    Name Description
    api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

    Data type: String
    req_defn_id Unique ID of the request definition.

    Data type: String

    Table: In the ID column of the Remote Request Definition [sn_ind_rmt_help_request_defn] table.
    task_id Sys_id of the task to return. This field is provided by the EMR system.

    Data type: String
    표 20. Query parameters
    Name Description
    None
    표 21. Request body parameters
    Name Description
    None

    Headers

    The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

    표 22. Request headers
    Header Description
    Accept Data format of the response body. Only supports application/json.
    표 23. Response headers
    Header Description
    None

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    표 24. Status codes
    Status code Description
    200 Successful. The request was successfully processed.
    401 Unauthorized. The user credentials are incorrect or have not been passed.
    500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

    Response body parameters (JSON)

    Name Description
    result Return results.

    Data type: Object

    "result": {
  "code": "String",
  "error": "String",  
  "errorTranslated": "String",
  "status": "String",
  "task_parameters": {Object},
  "warning": "String",
  "warningTranslated": "String"
}
    result.code Application error code when the result.status is returned as failure.

    Data type: String
    result.error Error message that is included if the result.status is failure.

    This message is in English only.

    Data type: String
    result.errorTranslated Optional localized error message.

    Data type: String
    result.status Status of the response.
    Possible values:
    • failure
    • success

    Data type: String
    result.task_parameters Required. Name-value pairs that describe the task parameters of the IT service request. Each element in the object corresponds to a column in the corresponding task tables such as the Incident [incident] table.

    Data type: Object
    result.warning Optional warning message. May be included if the result.status is success.

    This message is in English only.

    Data type: String
    result.warningTranslated Optional localized warning message.

    Data type: String

    cURL request

    Fetch data from a Cerner EMR system

    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"

    The following output shows both a successful response and an error response.

    // 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"
  }
}