Inbound web services allow you to access and modify ServiceNow data using a client application. When the client application calls the web service exposed by your ServiceNow instance, a return code (also called the "status code") will be provided in the response. The return code tells us how the request was handled. A status code in the 200 range (200, 201, 202) indicates a successful attempt to transmit the data from the client to the web server hosting the web service.
If you follow our Web Services Best Practices and configure your client to re-use the ServiceNow session, you may encounter a "202" return code in your client application. This does not indicate something is wrong, but it is important, as a client developer, to understand what implication this has concerning the request that you just sent into ServiceNow. Let's first look at exactly what a 202 really means:
202 ACCEPTED The request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place. |
The web service call being made from your client code has made it into ServiceNow, but the code tells us that the request might, or might not, be acted upon. The big question now is, "What will happen to my request if I get a 202 return code?". That is the ultimate question that this investigation will answer.
Causes of an HTTP 202 code
The cause of an HTTP 202 happens when a web service reuses the same session and requests come in quicker than they can be processed. As a result, we have too many requests for the same session waiting. This leads to new requests being returned with the 202 return code.
I ran a very contrived test that was designed to confirm exactly what happens when one session is used to send in many requests more quickly than they could be processed, and we exceed the default tuning values.
Testing the results of a request returning a 202 code
In my Geneva instance (also confirmed in Istanbul), I created a scripted REST web service that has a built-in 45 second delay. This REST service simply echoes the input value back to the client, and also updates a table with the input string and the timestamp that the web service was actually executed. This allowed me to confirm what data was received by the web service and exactly when the script executed code and processed the data.
My Scripted REST code is:
(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
gs.sleep(45000);
var body = request.body.data, echoString;
echoString = body.inputString;
var gr = new GlideRecord("u_counter");
gr.u_curtime = gs.nowDateTime();
gr.u_inputstring = echoString;
gr.insert();
return {
"inputString": echoString
};
})(request, response);
I also created a table called u_counter, which has 2 fields, u_curtime and u_inputstring.
Running the HTTP 202 test
Since this was a REST service, I used curl to call the web service. Curl provides a way to capture the cookies returned with the request, and also a way to reuse those cookies.
Here's the code from my shell script:
#!/bin/sh
run_curl_command()
{
# This command will be called in a loop that uses the cookie values stored in the cookiefile.txt file
curl "https://<Instance_Name>.service-now.com/api/now/delay45" -v --request POST \
--header "Accept:application/json" --cookie cookiefile.txt --header "Content-type:application/json" \
--data '{"inputString":"Loop Counter '"$i"'"}'
}
# This command is called 1 time to seed the cookie jar with the cookie values required for session reuse.
curl "https://<Instance_Name>.service-now.com/api/now/delay45/DelayedEcho" -v --request POST \
--header "Accept:application/json" --cookie-jar cookiefile.txt --header "Content-type:application/json" \
--data '{"delayTime":"1" ,"inputString":"Kickoff Message"}' --user 'admin':'fake_admin_password'
# Loop 99 times, each loop runs in the background, so we can fire all 99 loops without
# waiting for the previous request to complete before starting the next
# (basically, run 99 loops as quickly as we can, firing off 99 REST calls)
for i in {2..100}; do
run_curl_command &
done
The script will call the web service once, passing in the credentials the first call, but will then store all of the response cookies (including the session details) in the cookie jar. Then, we loop 99 times (for a total of 100 web service calls) that will pass in the existing cookies, and the loop counter, so we can track exactly how many of the 100 requests are processed, and with the loop counter being recorded, we can also see which calls actually complete.
We can see from the load balancer logs that, out of the 100 requests, we had 12 HTTP 200 and 88 HTTP 202 result codes returned. The number of 200's exactly matches the number of records that were updated in the table.
When an HTTP 202 result code is returned, we do not process that request.
When I pull a report from our Load Balancer (using Splunk), we can see the following details:
We can see that there were a total of 100 events captured, and the return codes show that we had 12 "HTTP 200" and 88 "HTTP 202" responses. Looking at the table that inserts all of the records that are processed through the scripted web service, we can see:
12 records were inserted, and client requests received an HTTP 200. All other requests were received by the web server, but did not get passed into the application code, and were never acted upon. This confirms that when a status code of 200 is returned, the data is processed by the web service. It also confirms that when a 202 is returned, the data is not processed by the web service.
Client applications should monitor the result code, and if a 202 is found, the request should be re-submitted (if it is important that all data be processed), but instead of using the cookie jar to reuse the session, a new session should be created and cookies stored for later reuse. Depending on what is typical for your environment and data, a return code of 202 may indicate a performance issue with your instance, so you may need to evaluate the calls being made and compared the expected execution time with the actual time.
1 Comment
