When testing APIs (Application Interfaces), it is always very helpful to get an independent view of the interfacing application. For example, if you are interfacing two ServiceNow instances, and it is not working as expected - how will you know where the error is - the source or the target of the integration? In this case, you will employ a 3rd party tool, such as the Firefox RESTClient, or Chrome's POSTMAN to test the REST integration. You can build tests to verify functionality such as POSTMAN.
For SOAP integrations, we typically use SOAP UI, which is already documented very well in Mini-Lab: Web Services — Part 1: Using SoapUI to Test ServiceNow WSDL. I will give you details on how to use RESTClient and POSTMAN for REST integrations with ServiceNow.
Let's start with the RESTClient, that can be downloaded into your Firefox browser as a plugin. For REST integrations, you will have a URL and a method. The standard methods are automatically available in the REST client including: GET, POST, DELETE, OPTIONS,HEAD, TRACE, and CONNECT.
You can read up on these methods (also called HTTP verbs) here: Hypertext Transfer Protocol - Wikipedia
How to retrieve a record from your Instance
To retrieve a record from your ServiceNow instance, you now have to do the following:
- Enter your URL (hint: look up the URL in your instance's REST API Explorer):
- You can click for example on cURL to get the URL:
--request GET \
--header "Accept:application/json" \
--user 'user':'password'
- In RESTClient, this will translate to:
The URL can be copied from the curl URL above.
The Content-Type header is added through the menu item Headers > Custom Headers and then filled as shown above, the Authorization Header is added through the menu item Authentication > Basic Authentication (add user name and password).
Other possible header values are found here: Supported REST API headers and other possible Authorization methods can be found here: REST API security
The response is in the JSON (Key-Value-Pair) format.
{ "result": [ { "parent": "", "made_sla": "false", "caused_by": "", "watch_list": "", "u_mobilecategory": null, "u_alternate_phone": "", "upon_reject": null, "sys_updated_on": "2016-12-08 08:03", "child_incidents": "", "approval_history": "", "skills": "", "number": "INC0000002", "resolved_by": "", "sys_updated_by": "system", "opened_by": { "display_value": "Joe Employee", "link": "https://instance.service-now.com/api/now/table/sys_user/681ccaf9c0a8016400b98a06818d57c7" }, "user_input": "", "sys_created_on": "2011-03-25 15:30", "sys_domain": { "display_value": "global", "link": "https://instance.service-now.com/api/now/table/sys_user_group/global" }, "state": "New", "sys_created_by": "pat", "knowledge": "false", "order": "", "u_cicat": "", "calendar_stc": "", "closed_at": "", "cmdb_ci": "", "delivery_plan": "", "contract": "", "impact": "1 - High", "active": "true", "work_notes_list": "", "business_service": "", "priority": "1 - Critical", "rfc": "", "time_worked": "", "expected_start": "", "rejection_goto": "", "opened_at": "2012-08-28 16:07", "u_eriktest": "", "business_duration": "", "group_list": "", "work_end": "", "caller_id": "", "resolved_at": "", "approval_set": "", "subcategory": "Operating System", "wf_activity": "", "work_notes": "2013-04-04 08:00 - Service-now: Person [maint,admin,itil] (Work notes) test 2013-04-04 07:57 - "short_description": "Can't get to network file shares", "close_code": null, "correlation_display": "", "delivery_task": "", "work_start": "", "assignment_group": { "display_value": "Software", "link": "https://instance.service-now.com/api/now/table/sys_user_group/8a4dde73c6112278017a6a4baf547aa7" }, "u_eriktest2": null, "additional_assignee_list": "", "business_stc": "", "description": "User can't get to any of his files on the file server.", "calendar_duration": "", "u_eriktest3": "", "close_notes": "", "notify": "Do Not Notify", "sys_class_name": "Incident", "closed_by": "", "follow_up": "", "parent_incident": "", "sys_id": "9d385017c611228701d22104cc95c371", "u_cisubcategory": "", "contact_type": "Phone", "incident_state": "Awaiting Problem", "urgency": "1 - High", "problem_id": { "display_value": "PRB0000007", "link": "https://instance.service-now.com/api/now/table/problem/9d3a266ac6112287004e37fb2ceb0133" }, "company": "", "reassignment_count": "2", "activity_due": "2016-12-08 10:03", "assigned_to": { "display_value": "Howard Johnson", "link": "https://instance.service-now.com/api/now/table/sys_user/46ca0887a9fe19810191e08e51927ebf" }, "severity": "1 - High",
{ "display_value": "Salem OR", "link": "https://empigeist2.service-now.com/api/now/table/cmn_location/108486c7c611227500b093211aa88dcc" }, "category": "software" } ] } |
Now that we know how to select a record or set of records, next we will create a new record in ServiceNow using the POST method:
The URL is the simple REST URL as documented, the Content Type and Authorization are the same as used in the GET method. The difference is in the Body - here we will fill the fields - in key value pairs defined by the JSON format. For example:
{"active":"true","category":"software","caller_id":"Abel Tuter","short_description":"REST POST DEMO"}
Will fill in the active, category, caller, and short description for the new incident.
The response shows the fields within the newly created record:
{ "result": { "parent": "", "made_sla": "true", "caused_by": "", "watch_list": "", "u_mobilecategory": "", "u_alternate_phone": "", "upon_reject": "cancel", "sys_updated_on": "2017-03-23 19:12:16", "child_incidents": "0", "approval_history": "", "skills": "", "number": "INC0010098", "resolved_by": "", "sys_updated_by": "admin", "opened_by": { "link": "https://instance.service-now.com/api/now/table/sys_user/6816f79cc0a8016401c5a33be04be441", "value": "6816f79cc0a8016401c5a33be04be441" }, "user_input": "", "sys_created_on": "2017-03-23 19:12:16", "sys_domain": { "link": "https://instance.service-now.com/api/now/table/sys_user_group/global", "value": "global" }, "state": "1", "sys_created_by": "admin", "knowledge": "false", "order": "", "u_cicat": "", "calendar_stc": "", "closed_at": "", "cmdb_ci": "", "delivery_plan": "", "contract": "", "impact": "3", "active": "true", "work_notes_list": "", "business_service": "", "priority": "5", "rfc": "", "time_worked": "", "expected_start": "", "rejection_goto": "", "opened_at": "2017-03-23 19:12:00", "u_eriktest": "", "business_duration": "", "group_list": "", "work_end": "", "caller_id": { "link": "https://instance.service-now.com/api/now/table/sys_user/62826bf03710200044e0bfc8bcbe5df1", "value": "62826bf03710200044e0bfc8bcbe5df1" }, "resolved_at": "", "approval_set": "", "subcategory": "", "wf_activity": "", "work_notes": "", "short_description": "REST POST DEMO", "close_code": "", "correlation_display": "", "delivery_task": "", "work_start": "", "assignment_group": { "link": "https://instance.service-now.com/api/now/table/sys_user_group/287ee6fea9fe198100ada7950d0b1b73", "value": "287ee6fea9fe198100ada7950d0b1b73" }, "u_eriktest2": "", "additional_assignee_list": "", "business_stc": "", "description": "", "calendar_duration": "", "u_eriktest3": "", "close_notes": "", "notify": "1", "sys_class_name": "incident", "closed_by": "", "follow_up": "", "parent_incident": "", "sys_id": "207d25b313a9b200d57c50f32244b07b", "u_cisubcategory": "", "contact_type": "phone", "incident_state": "1", "urgency": "3", "problem_id": "", "company": { "link": "https://instance.service-now.com/api/now/table/core_company/227cdfb03710200044e0bfc8bcbe5d6b", "value": "227cdfb03710200044e0bfc8bcbe5d6b" }, "reassignment_count": "0", "activity_due": "", "assigned_to": "", "severity": "3", "comments": "", "u_categorytier3": "", "u_sla_start_time": "", "approval": "not requested", "sla_due": "", "comments_and_work_notes": "", "due_date": "", "sys_mod_count": "0", "reopen_count": "0", "sys_tags": "", "escalation": "0", "upon_approval": "proceed", "correlation_id": "", "location": "", "category": "Software" } } |
The caller, which we entered by its display name of "Abel Tuter" is stored as a reference with the user record's sys_id, and default values that were filled via dictionary or business rules are also filled in.
Using external tools to validate your REST request and response is extremely helpful when troubleshooting REST integrations. You can compare your request and the response you receive within the external tool, to the results you expect in ServiceNow. These tools allow you to independently test both applications within an integration to ensure they are producing the expected results.
So, in a nutshell, that is how to use the RESTclient plugin. I am looking forward to providing a deep dive into the other frequently used external tool - POSTMAN (coming soon).
4 Comments
