Mini-Lab: Web Services — Part 3: Writing a Simple Scripted Web Service
Now that we have pretty much nailed down how to send query requests to the ServiceNow out-of-the-box default table WSDL let's move to something a bit more complex and useful!
In this article we will be constructing a simple scripted web service that will take an XML payload, and update a specified record in the CMDB Computer table (cmdb_ci_computer). This will require, of course, sending the XML via a SOAP Client to our new web service.
What is really cool about all of this is that we can set up this inbound XML to be anything we want. It does not have to follow any OOtB ServiceNow standard.
So, for this example I will be adding five new fields to the Computer table to hold additional CPU information that we might be able to garner from any Windows machine.
Prerequisites:
I highly recommend doing the Part 1 and Part 2 articles before proceeding with the labs in this article.
1. Some sort of SOAP Client installed on your test machine. In the lab I will be using SoapUI.
2. Create a web service user with itil and soap roles in ServiceNow.
3. Perform the first lab: Mini-Lab: Web Services — Part 1: Using SoapUI to Test ServiceNow WSDL
4. Perform the second lab: Mini-Lab: Web Services — Part 2: Using an Encoded Query
5. Some knowledge of ServiceNow Scripting would be useful.
6. Some knowledge of Scripted Web Services would be a bonus as well.
Scripted Web Services - ServiceNow Wiki
Scripted Web Service Tutorial - ServiceNow Wiki
Lab 1.1: Computer Table Setup
There are a couple of ways of adding new fields to an existing table. You can edit the table definition and add the fields (System Definition -> Tables), or you can go through the Form view of one of the records in that table and add the fields via Form Layout. Since Form Layout is the faster/easier method we will be using that.
1. Log on to your ServiceNow instance.
2. Navigate to Configuration -> Base Items -> Computers. The Computer list view will be displayed.
3. Edit one of the records. The form view will be displayed for that record.
4. Right-click on the form view header to display the context menu and navigate to Configure -> Form Layout. The Form Layout form will be displayed.
5. Add the following fields to the bottom of the first form section:
CPU Socket
CPU Architecture
CPU Processor Type
CPU Family
CPU Status
NOTE: For simplicity make all of these String with a length of 40.
6. Click the Save button to save your work. Your form should look something like this:
7. Grab the sys_id for this record by right-clicking on the form header to display the context menu, and choosing Copy sys_id. A pop-up window will appear showing the sys_id of the record. Copy the sys_id that is displayed to your favorite notepad. We will be using this in our Scripted Web Service. Close the pop-up window.
8. Right click on the field labels for each of the new fields. Note down each of the new field names. We will be using these in our Scripted Web Service as well. They should look like these:
u_cpu_socket
u_cpu_architecture
u_cpu_processor_type
u_cpu_family
u_cpu_status
That finishes setting up our table to receive the new values we will be sending in. Now we are ready to move to creating our Scripted Web Service!
Lab 1.2: Creating the Scripted Web Service
1. From your ServiceNow instance navigate to System Web Services -> Scripted Web Services. The Scripted Web Services list view will appear.
2. Click the New button. The new Scripted Web Service form will appear.
3. Fill in the form with the following:
a. Name: UpdateComputerCI
b. Active: True
c. Short Description: Update custom Computer CI fields
d. Script:
try {
xmldoc = new XMLDocument(soapRequestXML);
var sys_id = xmldoc.getNodeText("//sys_id") + '';
var cpuSocket = xmldoc.getNodeText("//cpu_socket") + '';
var cpuArchitecture = xmldoc.getNodeText("//cpu_architecture") + '';
var cpuProcessorType = xmldoc.getNodeText("//cpu_processor_type") + '';
var cpuFamily = xmldoc.getNodeText("//cpu_family") + '';
var cpuStatus = xmldoc.getNodeText("//cpu_status") + '';
gs.log('--->soapRequestXML: ' + soapRequestXML);
var computerRecords = new GlideRecord('cmdb_ci_computer');
if (computerRecords.get(sys_id)) {
computerRecords.u_cpu_socket = cpuSocket;
computerRecords.u_cpu_architecture = cpuArchitecture;
computerRecords.u_cpu_processor_type = cpuProcessorType;
computerRecords.u_cpu_family = cpuFamily;
computerRecords.u_cpu_status = cpuStatus;
computerRecords.update();
}
}
catch (err) {
gs.log('---> ERROR: ' + err, 'SWS: UpdateComputerCI');
}
Leave all the other fields to default. You could change the name of the function from "execute" to something else, but I felt this was pretty descriptive of what we would be doing so I left it.
I put a try/catch around the code to make sure we capture anything bad that might not have been anticipated. You could always slick this up by adding some checking on the in-bound values.
The variable soapRequestXML is reserved/built-in and will automatically contain our entire inbound XML payload. Using XMLDocument we convert the XML to an object then reference the fields we want to extract. I threw in the gs.log to print off what the XML looks like when it comes in.
Finally using the sys_id that was sent to our code we can update the existing computer record with our inbound values.
BTW, did you see how the displayed WSDL URL modified itself to contain the name of your Scripted Web Service?
e. Right-click on the Form header to display the context menu and click Save to save your work. This will cause the related fields tabs to appear at the bottom of the form.
f. Click on the Input Parameters tab, and click the New button. The new Input Parameters form will be displayed. Here we will be describing our one inbound variable that will contain our variables.
g. Fill in the form with the following:
i. Name: payload
ii. Leave all the other fields their default values.
iii. Click the Submit button to save the new Input Parameter.
iv. The Scripted Web Service form should be re-displayed.
h. Copy the WSDL URL to your notepad. We will be using this to verify the WSDL, and in our SOAP Client to test with.
4. Open a new browser tab and paste your WSDL URL into the navigation field to see your new WSDL. Note the inbound payload variable.
We are done with our Scripted Web Service!
Lab 1.3: Testing the Scripted Web Service
Now as the last step we need to set up our SOAP Client to test our new Scripted Web Service with! I will be doing this with SoapUI, but you could just as easily set this up with any other SOAP Client.
1. Open SoapUI.
2. Right-Click on Project to display the context menu, and click on New SOAP Project. The New SOAP Project form will be displayed.
3. Fill out the form with the following:
a. Project Name: Update Computer CI
b. Initial WSDL: Fill in your incident wsdl url here.
Example: https://dev00001.service-now.com/UpdateComputerCI.do?WSDL
c. Create Requests: Checked
d. Click the Ok button to display the Basic Authentication form.
4. The Basic Authentication form will appear.
5. Fill out the form with the user credentials you created back in the Part 1 article.
a. Username: svcuser
b. Password: your user's password.
c. Click on the Ok button to create the new Incident project.
6. In the left-hand tree view navigate down to and click on result1 to bring up the properties.
7. Fill in the following in the properties window:
a. Name: Update Computer
b. Username: svcuser
c. Password: the password for svcuser
8. From the tree view double-click on Update Computer. This will display the Update Computer XML.
9. In the Update Computer XML window change the XML to look like the following:
7f8a10d60fb3ca002ae14e9ce1050e42
CPU Socket - U3E1
x64
Central Processor
Intel CoreTM i5
CPU Enabled
The sys_id is the one you copied from your CMDB Computer record earlier.
Since I started out meaning these to be real fields (for the purposes of the next article) I have gone to the trouble here of showing real values that will be stored in the table. I pulled these manually from here:
10. Everything should now look something like this:
And now we are ready to test!!! Whoop! Trust me; this is worth it!
11. Now click on the green "start" button at the top of the Update Computer XML form. This will send our test XML to our new Scripted Web Service. You should see something like the following when it is done:
The response XML indicates a successful run. If you do not get anything back take a look at the SoapUI log and/or the http log at the bottom (press buttons).
Now let's check to see what happened on our instance!
12. In your ServiceNow instance navigate to System Logs -> System Log -> All
13. Set the filter to where "Message starts with --->"
14. You should see something like this:
This is our inbound XML captured for our study. Looks exactly as we sent it doesn't it? Well...sort of...close enough!
15. Now navigate to Configuration -> Base Items -> Computers. The Computer list view will be displayed.
16. Filter on where sys_id equals the value of the record that you copied out in Lab 1.1 above. You should see just your one record displayed. Edit that record.
17. You should see all of your new fields filled in something like the following:
That is all there is to it! You now have a model to play with that sends a simple XML payload into a Scripted Web Service that then updates values in a CMDB Computer record. Cool, huh?!
Steven Bell
If you find this article helps you, don't forget to log in and "like" it!
Also, if you are not already, I would like to encourage you to become a member of our blog!
Please Share, Like, Comment this blog if you've found it helpful or insightful.
For other Expert Knowledge
Ask A Developer What's In Store For IT Leaders in 2016 ServiceNow Online Learning Courses ServiceNow Foundations: User Interface
https://www.servicenow.com/community/developer-blog/mini-lab-web-services-part-3-writing-a-simple-scripted-web/ba-p/2287626