Script Debugger API

  • Release version: Xanadu
  • Updated August 1, 2024
  • 7 minutes to read

    • The Script Debugger API provides endpoints to debug lines of server-side JavaScript code, such as business rules and script includes.

    For more information about the Script Debugger, see Script Debugger and Session Log.

    This API is available by default.

    Script Debugger - GET /js/debugpoints/script/{tableName}/{sysId}/{fieldName}

    Retrieve a list of breakpoints or logpoints in a server-side script, such as a business rule or script include.

    URL format

    Default URL: /api/now/js/debugpoints/script/{tableName}/{sysId}/{fieldName}

    Supported request parameters

    Table 1. Path parameters
    Name Description
    tableName Name of the table that contains the server-side script, such as sys_script or sys_script_include.

    Data type: String
    sysId Sys_id for the server-side script.

    Data type: String
    fieldName Name of the field that contains the server-side script content.

    Data type: String
    Table 2. Query parameters
    Name Description
    None
    Table 3. Request body parameters (XML or JSON)
    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.

    Table 4. Request headers
    Header Description
    Accept Data format of the response body. Supported types: application/json or application/xml.

    Default: application/json
    Table 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.

    Table 6. Status codes
    Status code Description
    200 Successful. The request was successfully processed.
    403 User Not Authorized. The user who executed the request does not have permission to access breakpoint or log point information for the specified record.

    Response body parameters (JSON or XML)

    Name Description
    canWrite Flag indicating whether the currently logged in user can set or modify breakpoints for the script.
    Possible values:
    • true: You can set or modify breakpoints.
    • false: You cannot set or modify breakpoints.

    Data type: Boolean
    debugpoints List of all the breakpoints and logpoints in the script.
    "debugpoints": {
  "breakpoint": {Object}
  "logpoint": {Object}
}

    Data type: Object
    debugpoints.breakpoint List of all the breakpoints in the script, presented as key-value pairs. The key is the line number for the breakpoint. The value is an object containing the breakpoint's sys_id and text.
    "breakpoint": {
  <line_number>: {Object}
}

    Data type: Object
    debugpoints.breakpoint.<line_number> Line number for the breakpoint.
    <line_number>: {
  "evaluationString": "String"
  "sysId": "String"
}

    Data type: Object
    debugpoints.breakpoint.<line_number>.evaluationString Text of the breakpoint. If the breakpoint is conditional, the evaluationString contains the condition text. If the breakpoint is not conditional, the evaluationString is an empty string.

    Data type: String
    debugpoints.breakpoint.<line_number>.sysId Sys_id of the breakpoint.

    Data type: String
    debugpoints.logpoint List of all the logpoints in the script, presented as key-value pairs. The key is the line number for the logpoint. The value is an object containing the logpoint's sys_id and text.
    "logpoint": {
  <line_number>: {Object}
}

    Data type: Object
    debugpoints.logpoint.<line_number> Line number for the logpoint.
    <line_number>: {
  "evaluationString": "String"
  "sysId": "String"
}

    Data type: Object
    debugpoints.logpoint.<line_number>.evaluationString Text of the logpoint. Contains the message being logged.

    Data type: String
    debugpoints.logpoint.<line_number>.sysId Sys_id of the logpoint.

    Data type: String
    key Object providing details about the script being debugged. 
    "key": {
  "scriptField": "String"
  "scriptId": "String"
  "scriptType": "String"
  "value": "String"
}

    Data type: Object
    key.scriptField Name of the field that contains the script.

    Data type: String
    key.scriptId Sys_id of the script.

    Data type: String
    key.scriptType Name of the table that contains the script.

    Data type: String
    key.value The path parameters used to make the request. Listed in the following order.
    • tableName
    • sysId
    • fieldName

    Data type: String
    name Name of the script.

    Data type: String
    script Text displaying the script's code.

    Data type: String

    Example cURL request

    cURL request

    Retrieves a list of logpoints and breakpoints for a server-side script. This script has a logpoint on line 2, a breakpoint on line 11, and a conditional breakpoint on line 18.

    curl "https://instance.servicenow.com/api/now/js/debugpoints/script/sys_script_include/d65f78c40a0a0b6900196656f35913d3/script" \
--request GET \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--user 'username':'password'
    {
  "result": {
    "canWrite": true,
    "debugpoints": {
      "LOGPOINT": {
        "2": {
          "evaluationString": "A log message",
          "sysId": "ba28b0fa739310101c233096fbf6a75e"
        }
      },
      "BREAKPOINT": {
        "11": {
          "evaluationString": "",
          "sysId": "dc5f5bf341256010f877587fbdf5ec1d"
        },
        "18": {
          "evaluationString": "a == true",
          "sysId": "3d4f5bf341256010f877587bdf5ecf6"
        }
      }
    },
    "script": "// script code",
    "name": "AbstractAjaxProcessor",
    "key": {
      "scriptType": "sys_script_include",
      "scriptId": "d65f78c40a0a0b6900196656f35913d3",
      "scriptField": "script",
      "value": "sys_script_include.d65f78c40a0a0b6900196656f35913d3.script"
    }
  }
}

    Script Debugger - POST js/debugpoints/process

    Add, update, or remove breakpoints or logpoints in a server-side script, such as a business rule or script include. Process several breakpoints or logpoints at a time.

    URL format

    Default URL: /api/now/js/debugpoints/process

    Supported request parameters

    Table 7. Path parameters
    Name Description
    None
    Table 8. Query parameters
    Name Description
    fetchAll When true, returns a list of all the breakpoints or logpoints added or updated by the user.

    Data type: Boolean

    Default: false
    fetchAllFilter

    Returns a filtered list of all the breakpoints or logpoints added or updated by the user.

    Valid values:
    • debugpointType. Set to either breakpoint or logpoint.
    • scriptId. Set to the sys_id of the script in which to search for debug points.
    • scope. Set to the name of the scope in which to search for debug points.

    Use the caret (^) symbol as a separator for multiple properties. For example, fetchAllFilter=debugpointType=logpoint^scope=MyApp

    Data type: String
    Table 9. Request body parameters (XML or JSON)
    Name Description
    debugpointType

    Required. Type of debug point to add, delete, or update.

    Valid values:
    • breakpoint
    • logpoint

    Data type: String
    evaluationString

    Text for a logpoint or conditional breakpoint.

    For a logpoint, the evaluationString is the log message.

    For a conditional breakpoint, the evaluationString is the condition. For example, if you're looping through a list of user IDs and you want the debugger to pause only when the user ID is 38493, you can add a conditional breakpoint inside the loop with userID == 38493 as the condition. The debugger will only pause at this breakpoint when the condition is true.

    If the breakpoint is not a conditional breakpoint, the evaluationString is an empty string.

    Data type: String
    fieldName Required. Name of the field that contains the server-side script content.

    Data type: String
    lineNumber Line number in the server-side script specifying where to add, delete, or update the breakpoint or logpoint.

    Data type: Number
    operation Required. Operation to perform for the breakpoint or logpoint.
    Valid values:
    • add
    • delete
    • update

    Data type: String
    scriptId Required. Sys_id for the server-side script.

    Data type: String
    tableName Required. Name of the table that contains the server-side script, such as sys_script or sys_script_include.

    Data type: String

    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.

    Table 10. Request headers
    Header Description
    Accept Data format of the response body. Supported types: application/json or application/xml.

    Default: application/json
    Content-Type Data format of the request body. Supported types: application/json or application/xml.

    Default: application/json
    Table 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.

    Table 12. Status codes
    Status code Description
    200 Successful. The request was successfully processed.

    Response body parameters (JSON or XML)

    Name Description
    requestedDebugpoints List of the requested breakpoints and logpoints. Presented as an array of objects.
    "requestedDebugpoints": [
  {
    "scriptId": "String",
    "evaluationString": "String",
    "operation": "String",
    "tableName": "String",
    "fieldName": "String",
    "status": "String",
    "lineNumber": Number,
    "debugpointType": "String"
  }
]

    Data type: Array
    requestedDebugpoints.ScriptId Sys_id for the server-side script.

    Data type: String
    requestedDebugpoints.evaluationString Text added for a logpoint or conditional breakpoint. For a logpoint, the evaluationString is the log message. For a conditional breakpoint, the evaluationString is the condition.

    Data type: String
    requestedDebugpoints.operation

    Operation performed for the breakpoint or logpoint.

    Possible values:
    • add
    • delete
    • update

    Data type: String
    requestedDebugpoints.tableName Name of the table that contains the server-side script, such as sys_script or sys_script_include.

    Data type: String
    requestedDebugpoints.fieldName Name of the field that contains the server-side script content.

    Data type: String
    requestedDebugpoints.status

    Result of the instruction to add, delete, or update a specific breakpoint or logpoint.

    Possible values:
    • failure
    • ignored
    • success
    A request to add, delete, or update a debug point is ignored in the following situations:
    • It requests to delete a breakpoint or logpoint that doesn't exist.
    • It requests to add a breakpoint or logpoint identical to one that already exists.

    Data type: String
    requestedDebugpoints.lineNumber Line number in the server-side script specifying where the breakpoint or logpoint was added, deleted, or updated.

    Data type: Number
    requestedDebugpoints.debugpointType

    Type of debug point added, deleted, or updated.

    Possible values:
    • breakpoint
    • logpoint

    Data type: String
    status Result of the overall action. The status code for the HTTP call.

    Data type: Number

    cURL request

    This example adds a conditional breakpoint at line 12 in the script.

    curl "https://instance.servicenow.com/api/now/js/debugpoints/process" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data “[
{
\"tableName\": \"sys_script_include\",
\"scriptId\": \"d65f78c40a0a0b6900196656f35913d3\",
\"fieldname\": \"script\",
\"lineNumber\": 12,
\"evaluationString\": \"a == false\",
\"debugpointType\": \"breakpoint\",
\"operation\": \"add\"
}
]” \
--user 'username':'password'
    {
  "result": {
    "requestedDebugpoints": [
      {
        "scriptId": "d65f78c40a0a0b6900196656f35913d3",
        "evaluationString": "a == false",
        "operation": "add",
        "tableName": "sys_script_include",
        "fieldName": "script",
        "status": "success",
        "lineNumber": 12,
        "debugpointType": "breakpoint"
      }
    ],
    "status": 200
  }
}