Published on March 11, 2020.

I'm currently working on a ServiceNow integration project, and one of the requirements is that the external system (which in this case is NetSuite) needs to be able both add and retrieve the comments and work notes that are associated with an incident.

The screen shot below is an example of a ServiceNow incident with three comments attached to it. They're listed in the "Activities" area of the form. (Note that there is an additional audit-related entry that lists the field changes.)

In this blog post, I'll show how you can use the ServiceNow Table API to both retrieve and add comments and work notes to an incident.

Retrieving Work Notes: Method 1

If you make a call to the ServiceNow Table API to retrieve an incident, you'll find that the work notes are included in the response.

For example, here's a request to retrieve the incident.

curl "https://ironforge.service-now.com/api/now/table/incident/a79d926cdb234010e6e80d53ca9619fe?sysparm_limit=10&sysparm_display_value=true" \
     -H 'Accept: application/json' \
     -u 'flashgordon:03fcb0c0-b14a-4941-8a59-81f41db750f1'

The response looks like this:

{
  "result": {
    "parent": "",
    "made_sla": "true",
    "caused_by": "",
    "watch_list": "",
    "upon_reject": "Cancel all future Tasks",
    "sys_updated_on": "2020-03-11 04:32:59",
    "child_incidents": "0",
    "hold_reason": "",
    "approval_history": "",
    "number": "INC0010001",
    "resolved_by": "",
    "sys_updated_by": "admin",
    "opened_by": {
      "display_value": "Tim Dietrich",
      "link": "https://ironforge.service-now.com/api/now/table/sys_user/825d562cdb234010e6e80d53ca9619a5"
    },
    "user_input": "",
    "sys_created_on": "2020-03-11 04:24:18",
    "sys_domain": {
      "display_value": "global",
      "link": "https://ironforge.service-now.com/api/now/table/sys_user_group/global"
    },
    "state": "New",
    "sys_created_by": "tim.dietrich",
    "knowledge": "false",
    "order": "",
    "calendar_stc": "",
    "closed_at": "",
    "cmdb_ci": "",
    "delivery_plan": "",
    "contract": "",
    "impact": "3 - Low",
    "active": "true",
    "work_notes_list": "",
    "business_service": "",
    "priority": "3 - Moderate",
    "sys_domain_path": "/",
    "rfc": "",
    "time_worked": "",
    "expected_start": "",
    "opened_at": "2020-03-11 04:24:18",
    "business_duration": "",
    "group_list": "",
    "work_end": "",
    "caller_id": {
      "display_value": "Tim Dietrich",
      "link": "https://ironforge.service-now.com/api/now/table/sys_user/825d562cdb234010e6e80d53ca9619a5"
    },
    "reopened_time": "",
    "resolved_at": "",
    "approval_set": "",
    "subcategory": null,
    "work_notes": "2020-03-11 04:26:20 - System Administrator (Work notes)
Server is now responding to internal requests.

",
    "short_description": "Database Server LS7 is down.",
    "close_code": null,
    "correlation_display": "",
    "delivery_task": "",
    "work_start": "",
    "assignment_group": "",
    "additional_assignee_list": "",
    "business_stc": "",
    "description": "Database Server LS7 is down.",
    "calendar_duration": "",
    "close_notes": "",
    "notify": "Do Not Notify",
    "service_offering": "",
    "sys_class_name": "Incident",
    "closed_by": "",
    "follow_up": "",
    "parent_incident": "",
    "sys_id": "a79d926cdb234010e6e80d53ca9619fe",
    "contact_type": "Self-service",
    "reopened_by": "",
    "incident_state": "New",
    "urgency": "1 - High",
    "problem_id": "",
    "company": "",
    "reassignment_count": "0",
    "activity_due": "UNKNOWN",
    "assigned_to": "",
    "severity": "3 - Low",
    "comments": "2020-03-11 04:32:59 - System Administrator (Additional comments)
The server appears to be back online. It's responding to internal pings. We're currently working to confirm that the dependent Web applications have connectivity.

2020-03-11 04:24:38 - Tim Dietrich (Additional comments)
Server is not responding to pings.

2020-03-11 04:24:18 - Tim Dietrich (Additional comments)
Database Server LS7 is down.

",
    "approval": "Not Yet Requested",
    "sla_due": "UNKNOWN",
    "comments_and_work_notes": "2020-03-11 04:32:59 - System Administrator (Additional comments)
The server appears to be back online. It's responding to internal pings. We're currently working to confirm that the dependent Web applications have connectivity.

2020-03-11 04:26:20 - System Administrator (Work notes)
Server is now responding to internal requests.

2020-03-11 04:24:38 - Tim Dietrich (Additional comments)
Server is not responding to pings.

2020-03-11 04:24:18 - Tim Dietrich (Additional comments)
Database Server LS7 is down.

",
    "due_date": "",
    "sys_mod_count": "3",
    "reopen_count": "0",
    "sys_tags": "",
    "escalation": "Normal",
    "upon_approval": "Proceed to Next Task",
    "correlation_id": "",
    "location": "",
    "category": "Inquiry / Help"
  }
}

The two values to look at are "comments" and "comments_and_work_notes." The values look very similar, but there is a slight and potentially important difference between them. The "comments" value includes entries that are visible to the customer, while the "comments_and_work_notes" value also includes entries that are are intended for use by the IT team only.

Also, notice that the values in both fields include entries that are delimited by two carriage returns. You could use something like PHP's explode function to create an array of the entries.

Retrieving Work Notes: Method 2

Another method for retrieving the work notes and comments for an incident is to make a call to the ServiceNow Table API and, instead of retrieving the incident, retrieve the work notes and comments directly. To do this, you make a GET request to the sys_journal_field table, and specify the system ID (sys_id) of the incident.

Here's an example request:

curl "https://ironforge.service-now.com/api/now/table/sys_journal_field?sysparm_limit=100&element_id=a79d926cdb234010e6e80d53ca9619fe" \
     -H 'Accept: application/json' \
     -u 'flashgordon:03fcb0c0-b14a-4941-8a59-81f41db750f1'

And the response will look similar to this:

{
  "result": [
    {
      "sys_id": "583e56acdb234010e6e80d53ca961968",
      "sys_created_on": "2020-03-11 11:26:20",
      "name": "incident",
      "element_id": "a79d926cdb234010e6e80d53ca9619fe",
      "sys_tags": "",
      "value": "Server is now responding to internal requests.",
      "sys_created_by": "admin",
      "element": "work_notes"
    },
    {
      "sys_id": "6bcd526cdb234010e6e80d53ca9619b9",
      "sys_created_on": "2020-03-11 11:24:38",
      "name": "incident",
      "element_id": "a79d926cdb234010e6e80d53ca9619fe",
      "sys_tags": "",
      "value": "Server is not responding to pings.",
      "sys_created_by": "tim.dietrich",
      "element": "comments"
    },
    {
      "sys_id": "a6bd16acdb234010e6e80d53ca9619d0",
      "sys_created_on": "2020-03-11 11:24:18",
      "name": "incident",
      "element_id": "a79d926cdb234010e6e80d53ca9619fe",
      "sys_tags": "",
      "value": "Database Server LS7 is down.",
      "sys_created_by": "tim.dietrich",
      "element": "comments"
    },
    {
      "sys_id": "b5bf926cdb234010e6e80d53ca9619df",
      "sys_created_on": "2020-03-11 11:32:59",
      "name": "incident",
      "element_id": "a79d926cdb234010e6e80d53ca9619fe",
      "sys_tags": "",
      "value": "The server appears to be back online. It's responding to internal pings. We're currently working to confirm that the dependent Web applications have connectivity.",
      "sys_created_by": "admin",
      "element": "comments"
    }
  ]
}

There are a couple of things worth noting about the response. First, it includes both work notes and comments. Also, the entries appear to be out of order. (They're actually sorted by their sys_id values.)

To resolve those issues, we can specify an "element" and "sysparm_query" value in the request. For example:

curl "https://ironforge.service-now.com/api/now/table/sys_journal_field?sysparm_limit=100&element_id=a79d926cdb234010e6e80d53ca9619fe&element=comments&sysparm_query=ORDERBYDESCsys_created_on" \
     -H 'Accept: application/json' \
     -u 'flashgordon:03fcb0c0-b14a-4941-8a59-81f41db750f1'

The response will now look similar to this:

{
  "result": [
    {
      "sys_id": "b5bf926cdb234010e6e80d53ca9619df",
      "sys_created_on": "2020-03-11 11:32:59",
      "name": "incident",
      "element_id": "a79d926cdb234010e6e80d53ca9619fe",
      "sys_tags": "",
      "value": "The server appears to be back online. It's responding to internal pings. We're currently working to confirm that the dependent Web applications have connectivity.",
      "sys_created_by": "admin",
      "element": "comments"
    },
    {
      "sys_id": "6bcd526cdb234010e6e80d53ca9619b9",
      "sys_created_on": "2020-03-11 11:24:38",
      "name": "incident",
      "element_id": "a79d926cdb234010e6e80d53ca9619fe",
      "sys_tags": "",
      "value": "Server is not responding to pings.",
      "sys_created_by": "tim.dietrich",
      "element": "comments"
    },
    {
      "sys_id": "a6bd16acdb234010e6e80d53ca9619d0",
      "sys_created_on": "2020-03-11 11:24:18",
      "name": "incident",
      "element_id": "a79d926cdb234010e6e80d53ca9619fe",
      "sys_tags": "",
      "value": "Database Server LS7 is down.",
      "sys_created_by": "tim.dietrich",
      "element": "comments"
    }
  ]
}

Notice that this response only includes the comments, and that they are sorted in reverse chronological order based on the date that they were created (sys_created_on).

One more note about this approach: If you use ServiceNow's REST API Explorer, the table that we're accessing (sys_journal_field) is not available as an option. Regardless, the Table API does support it.

Adding Work Notes

To add a work note to an incident, you make a POST, PUT, or PATCH request to the Table API, and specify either a value for "comments" or "work_notes." You'd use "comments" to add a comment that customers can see, and "work_notes" for an internal-only entry.

Here's an example, where we're making an API call to add a work note to an existing incident.

curl -X "PATCH" "https://ironforge.service-now.com/api/now/table/incident/a79d926cdb234010e6e80d53ca9619fe?sysparm_limit=10" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -u 'flashgordon:03fcb0c0-b14a-4941-8a59-81f41db750f1' \
     -d $'{
  "work_notes": "A test work note."
}'

Wrapping Up

In this blog post, I've shown examples of how you can use the ServiceNow Table API to both retrieve and add comments and work notes to an incident. While the examples focused on incidents, it's worth noting that these same techniques can also be used with other tables, including Catalog Request Items (RITMs) and Catalog Tasks.

I hope you found this information helpful. If you have any questions or comments, please feel free to reach out to me.