This is the first in a multi-part series on APIs and Integration to help the community better understand integration, APIs, one of the most popular topics in cloud computing. Let's discuss and build up our community. If I missed anything or have made mistakes please let me know in the comments. Also questions are welcome. I really want to start a discussion here!
First lesson: You've already done integration - you just didn't know it.
"But Paul! I'm not technical! How could I have done integration?" you exclaim.
I assure you if you've been in sales, especially if you're not technical, you've possibly done more integration than most technical people.
You've done integration every time you've had to upload a list of contacts to a cloud based CRM or downloaded a list of prospects into CSV (Excel) to create a call list. Think about all the times you've pulled a list from the cloud. How many times has that gross XML code reared its ugly head? How many times did a cloud service refuse your upload because you had the date and time format wrong? How many times have your sorted and cleaned a mess of a list transforming it into useful data where you can call those contacts, take notes, and get your work done? All salespeople have spent time in excel whether they admit it or not to the sales manager ;). Now that you're a Solutions Consultant I want to make this leap as easy for you as possible and use your experience to your benefit.
If you've taken the Advanced Admin you may remember this image
Notice I have Excel highlighted. You can see XML there also as well as HTTP/FTP (FTP may be familiar) and even JDBC (Hint: the DB stands for Data Base).
Notice the large vertical rectangle that says 'Transform', seems pretty technical and scary right? No! Remember you've already done integration - transform is just like those Excel formulas that you're already familiar with like: Date(), DateValue(), SUM(), TextJoin(), VLookup(). You've got this!
OK! Are you pumped up!?!? you better be because we're going to build your first API.
One of the COOLEST new things to come out of Quebec is the REST API trigger. I was so excited to see this because this knocks out the midrange API Integration players and elevates the ServiceNow Integration Hub and Flow designer. It allows you to create and manage your own APIs! APIs are truly the building blocks of the internet. Every time you go to a website, look at a list of open cases, download a PDF, log into your bank, you're using APIs. Now you're going to build one!
I hate to just point you over to those instructions and say "Now I've got you all excited - go do this exercise" but that's what I am going to do because the best way to understand APIs and Integrations is to build them yourself and I (we/community) am going to do by best over this series to teach you how to do this so you can win more deals and make more money. Whenever you're in talks with a prospect about integration they're going to say "PROVE IT" so I want to show you some ways to prove integration without having to have logins for a bunch of systems and minimal software and gain a level of comfort now.
Ok so here's a couple of tips to help you along the way in reference to the hyperlinked doc.
First of all follow along on the doc even though it may not make sense right away, I am going to try to ask the doc team to make some adjustments and in the meantime here's some of my commentary.
On Procedure step 10 the assignment group of incident is mentioned but they don't really tell you how to get that assignment group. I suggest searching Incident in the ServiceNow UI and looking at all open incidents then clicking on the (i) icon next to the assignment group (IT securities for example) and in the hamburger clicking on 'Copy sys_id'
On Procedure step 11 it shows the REST API explorer but I have not been able to duplicate that yet. Rest API explorer is very cool, I think we'll talk about it in another article.
Instead of using the REST API explorer you can use flow designer to test. Click on the Test button and utilize the sys_id you copied in the above step 10 to test the API.
Now when you click on that hyperlink 'Your test has finished running. View the flow execution details' you're going to see all of the plumbing of the internet - remember, you've done this before - so let's walk through the info a little.
Notice I've highlighted the configuration details in yellow and the runtime value in green.
I know it seems like we're in the Matrix right now but I assure you, you just told the computer what to do and it's doing it, you did this! The configuration details are all the info that you setup in Flow Designer, you pasted in the Path Parameter of the sys_id for the assignment group, and you typed in the string data for the description. You also told the flow designer to accept application/json the role you assigned etc...etc... the API is just doing what you've told it to do.
Now the next big leap in your integration journey happens here:
12. Configure the REST request from your third-party system.
This is sometimes painful and while pain can sometimes be a worthwhile experience I think you might find this a big turn off and get frustrated. I have an alternative - see below.
A couple of points on this part of the exercise:
I'd suggest copying and pasting the CURL request into a text editor so you can manipulate the text.
curl "https:your-instance.servicenow.com/api/now/create_incident_from_external_event/assignment_group/287ebd7da9fe198100f92cc8d1d2154e" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
fields: {
description: \"Major outage with data loss\"
}
}" \
--user 'username':'password'Be careful copying and pasting - Macs seem to have a quirk where they put a `` backwards facing quote where there should be a " vertical quote - so you might get some errors in the copy paste like I did. Remember the exercise told us to copy the sys_id for the Assignment group and put that in the URL path of our API. Once you have your URL you're going to go into the terminal and paste that curl request in and run it and you'll get results like the doc describes.
A wonderful alternative to terminal and CURL:
Ok let's take your hard-won new skills to the next level and introduce you to one of the best API testing tools in the world, it's called Postman. Postman is a super powerful tool for testing APIs - I leaned on it heavily in my past life as an integration architect. Download and install Postman and let's get crackin'!
Let's recreate that CURL request in Postman and test our API:
Postman is like a web browser for APIs - hit the + button in the tabs and you'll see a space for your URL - it may ask you to create a collection, ServiceNow is a good name, and it will probably have you name the test you're going to run, mine is named 'webhook test'. You'll find the interface very modern and easy to navigate. There's 3 panels you'll need to configure. You'll paste the URL into the postman browser bar, also hit the dropdown on the left to select POST. From the CURL request you can copy and paste into the body field. Be sure to remove any \ back slashes and don't forget the curly braces.
Notice I have the URL in the box in the green and the JSON Body pasted into the 'raw' selection circled in yellow.
Next you'll put the headers in (red circle), most of this will auto-fill as you type a little (blue circle):
You'll also need to authenticate with the proper username and password through basic auth:
Now you're ready to start testing your API go ahead and hit send as many times as you'd like, change the description message in the 'Body' section to say whatever you'd like and browse to incidents to see the incidents rolling in!
Now there's a little hidden secret in Postman for the integrator and it's really cool. Notice how this testing has evolved, we've gone from testing within the Flow Designer, to CURL, to postman, how do we make the leap from testing tools to actual integrations? Sometimes it's tools like integration hub but other shops sometimes prefer code. Notice on the right margin of Postman a symbol that looks like this </> click on it and you'll see in the dropdown and panel all sorts of working code samples like JAVA, JavaScript, C, C#, PHP, and many many more.
WOW!! Look how far you've come!
Let's Modify our API:
I am going to go out on a limb and editorialize the API that was suggested we build from the docs. After all I was an integration architect (eye roll - lol). One thing I don't like about this API is the Path Parameter is the assignment group sys_id. I find this a little awkward and I think it limits our API for future modification. So I am going to pull that sys_id into the JSON body.
I hope you can see that - it's cut off a little on the bottom - we are removing the path parameter from the URL path, adding it into the Body as JSON, and also removing that below in the path parameter variable below. We'll get a message saying we are deleting stuff and that's ok go ahead with the delete.
Now we'll have to add that assignment group back into the "Create Incident Record Step" - that deletion above will wipe a lot of our configuration out so we'll need to select Incident as the Table and the two fields 'Assignment Group' and 'Short Description' and we'll also drag and drop those variables from the request body.
Test it! Save it! Activate it!
Now try it again in Postman! :cat_scream_emoji:
You'll have to edit the JSON body (don't forget the quotes and comma):
{
"fields": {
"assignment_group":"5f6441efc0a8010e0177fcb589156352",
"description": "Major outage with data loss"
}
}
and cut the '/assignment_group/5f6441efc0a8010e0177fcb589156352' off the URL.
Test it again!
If you've come this far then you deserve a pat on the back and a "well done!!"
Now a final thought in the denouement of this saga, this voyage through the time and space continuum of the inter-webs and inter-zones where we have faced so many perils together.
You have done this before you just didn't know it, most of the cloud is built this way and re-faced with different UIs. It may be a leap to go from excel to APIs and JSON but you've been downloading and uploading data to the web since forever. One of the reasons why I decided to re-architect the API a little was so I could show you an example of how this data could look in excel and I found the path parameter was causing me a little grief. The path parameter of assignment_group for Incidents seemed to interfere with my natural desire for the API itself to be simple and self-documenting. One way I could fix this would be to change the name from webhook_test to webhook_incident or something more self explanatory. I'm not quite there yet on what I am going to decide to call this API and I feel like before this series is over it'll change names again. BLAH too much architecture talk.
Finally, when you see JSON like this just smile and turn your head like this emoji 🙂 putting your left ear on your left shoulder. You'll see the JSON object go from this:
{
"fields": {
"assignment_group":"5f6441efc0a8010e0177fcb589156352",
"description": "Major outage with data loss"
}
}to this:
See what you did? From your experiences uploading human readable and human useable data, you're moving quickly into the integration, API, and automation space. You know this, you just don't know that you know this!
It's a good thought to leave you with. Have fun with this REST API triggers are really cool, Integration Hub and Flow Designer are very powerful.
More to come!
