Transcript

X-TIMESTAMP-MAP=LOCAL:00:00:00.000,MPEGTS:0 [MUSIC PLAYING] Welcome to Integrations for Fun and Profit. My name is Eric Riemer. I'm the development team lead for the ServiceNow practice at New Access Innovations. We're a ServiceNow partner working exclusively in the federal government space. I'm also a 2021 and 2022 ServiceNow Developer MVP. I work on a lot of interesting projects, but that's not actually why we're here, to talk about me. In this session, we're going to integrate, have fun, and profit. More seriously, we're going to go through what integration is, build some examples, and give you some tools that you can go and learn more yourself. So first, what is an integration? Well, there are so many terms that people use, as if you should just know what they all are. And this long list is only a few of them. The good news, you don't need to actually know most of them to get started. Eventually, yeah, you're going to have to learn a lot of them. But up front, very few are actually going to be important. So we don't need to boil the ocean. And let's simplify things. So there's only two things that you really need to start off knowing. What is an integration? And that's when computers talk to other computers to exchange information or take actions. And yeah, that's a gross oversimplification. The second is, what is an API? It stands for Application Programming Interface, which you don't actually need to know. What you do need to know is that it is the agreed-upon ways for the computers to talk to each other. So let's look at some examples of how to do this. So there's two major buckets that all integrations fall into. The first one is inbound. That's when somebody else is going to talk to you, rather than you talking to them. So some examples of this is a SRAPI-- a Scripted REST API. It gives you total control. It's my favorite one to use. There's out-of-the-box APIs, like the Table API and the Import Set API. They're out of the box. They're there. You don't have to lift a finger for them to exist. And they're super well-documented. Finally, there's the Flow Designer API trigger. And this one is super low code. You don't have to know any code whatsoever to use it. It does have the caveat that it's asynchronous. So you can't return any data. Makes it not so useful if somebody says, hey, give me the details of this record. But it is potentially really useful for somebody wanting to insert a new record, if you want to do that. Now, no matter which one you choose, you can and should make use of the REST API Explorer for testing. You can find it by filtering the Left Nav or the All menu, if you're using the Next UI. And one of the bonuses, not only can you test it that way by setting all your parameters, but it'll even give you code snippets that you can then pass along to that third party developer of like, here is everything you need to talk to this API correctly, so that they're not stuck only searching through documentation. Especially if you made a scripted REST API or a Flow Designer API trigger, if you didn't write that documentation, it doesn't exist. But at least you can give them, without having to write anything, here's how to call my API. And here's the code in the language that you're using to do it. So now let's get into an example, Scripted REST API. There's going to be a bunch of code, but it's not that scary. So here's the quick tour of what we're going to be looking at here. OK, so the first is a URL to call this API. The part in green is ServiceNow provided. It's your instance URL slash API slash your company code. Every company has a unique code. Even PDIs have a company code. So if you're just playing with this in a personal developer instance, you totally can. The next part in orange are the name you gave the API, a question mark, and the parameter name that you defined. And finally, in white is the actual value that's going to be sent as a parameter. You can have a whole bunch of parameters. I'm keeping it simple and only having one. And I'm expecting to receive an incident number. And I'm going to return some details. So here's the rest of the code. Again, looks like a lot. Not actually as scary as it might look. So lines 3 and 4 are just to grab the parameters from that payload that got sent. And so in this case, it's saying, find the number of parameter. And we're going to just hang on to that for a second. And line 7, we're going to do a GlideRecord.get on that record. And if it exists, build a payload of information to return. Pretty straightforward stuff, even if you don't understand what the heck this payload is supposed to look like. It's a JSON object. Almost doesn't even matter, because you're returning it to somebody else who needs to be able to handle that. Line 20 sets the response body with that payload that you're sending to them. Line 21 is the HTTP status. Those are those weird codes that you see and hear about, like 404, page not found, and 500 error, and whatnot. In this case, it's a 200, which just means you did it. You're good. And that's going to be returned to them. Line 22 deals with the bad incident number. Somebody sends me a number that doesn't exist, I'm going to send them a 404 not found message and an error saying, you gave me a bad number. And just like that, I've built a Scripted REST API endpoint that I can then make, that somebody else can call. And then they can get the information that they need. Now, the second major bucket of integrations is outbound. That's where you're going to send a message out to a different system and either get some information back from it or have it take an action. You should know, there might be ServiceNow licensing implications, depending on your contract. Ask your ServiceNow sales rep, if you have any questions about that. Because every contract is different, and I have no idea what yours says. So the easiest way to do this is to use an existing Integration Hub Spoke. There's a whole lot of them. ServiceNow keeps on coming up with more of them. Low code. It's great to use. If one of those doesn't exist, you can also make your own spoke. It's not actually that hard, and we're going to do an example of that in just a few minutes here. And it's pretty simple. It's sometimes even no code to build an entire outbound message that you can then do stuff with. Next is REST Message. This is the pro code way to do it, where you're going to have to write a bunch of code. You need to understand more what you're doing. But it gives you far more control. It also lets you test it with example parameters and see if you're getting back the results that you expect or not. Finally, there's Recordless REST, which is even more pro code. It doesn't have a REST message record that you'd find in the navigator. It just exists in a business rule or something, and that's the only place it exists. Another downside of it is it limits reusability, because it only exists in that one place. So we already built an example of an inbound API. So let's talk about how to make an outbound one. So how do you get started with that? Well, go find the API documentation, and then you might panic a little bit. This is the ServiceNow documentation to use the table API to get the details of one single record. It's fairly representative of what good API documentation looks like. It looks really long and complicated, doesn't it? And it's only one simple-sounding use case for an API. So let's break this down as we build a custom action and Flow Designer so that we can make use of it. So in the interest of time, we're not going to go through every single painful step. But basically, you go to Flow Designer. You go to New, Action, give it a name. We defined an input and added a REST step. And that's where I'm going to jump to on the next slide. And we're going to go through side-by-side with the documentation and what we're doing within that custom action in order to build on it. So I'm doing this with the ServiceNow API documentation that I just showed you. But any API should have similar documentation. Some APIs have absolutely horrid documentation, and I can't help you with that. I'm sorry. You just have to suffer through it. So we're going to do a GET. That's why we set the HTTP method, because I want to get information back into my system. I also copied the URL format into the resource path. And all of those parts surrounded by curly brackets are variables that we're going to need to replace. So those are the path parameters that we're going to replace them with. To make a simple example, I'm hardcoding in the incident table. So this action will get the details of an incident. And then I use the data pill from my input for the sys ID that I want to retrieve the details for. I'm skipping over the connection details, because depending on what you're integrating with, there are a lot of different authentication methods. Everything from a very basic username and password, or sometimes even no authentication, to far more complicated things that are way outside the scope of what I can talk about here today. But there's a lot of good documentation out there when you're looking for specific information about different authentication methods. Next, we have the query parameters. In this case, I set two of them. If you don't set them, they might have default values. The documentation is going to let you know if they're required or optional, and if they're optional, what the default is going to be. Just like the path on my last slide, I can stick the variable pills here from my input or anywhere else in my action, if I want to automate setting those or let the user, when they run those action, define it. In this case, I'm telling it that I want to get all of the details about the fields that I'm asking for-- not just the display value. Not just the raw value, but I want both for each of them. And that I only want to get back the values of a certain subset of fields. I don't want all of them. I only care about a couple of fields. Next up, we have headers. Same thing applies about optional versus required headers as well as the default values. In this case, ServiceNow is saying, well, would you like the response to be JSON or XML? In this case, we're just leaving it blank. We don't even need to set anything, because we're happy with JSON. Different APIs are going to have sometimes more, sometimes fewer things that you can set as your query parameters, header, body. That's why there's documentation. It'll tell you what you need to be building and setting. So great news, we built the request. And now we have to deal with the response that comes back to us. So the docs tell us we're getting name-value pairs. And we already saw that it's JSON name-value pairs. So I added a JSON parser step. And in that step, I set the source data field to the response body data pill from the request. So we finish the request step. We grab the output of that, put it into basically the input of this JSON parser. And the API docs were nice enough to give us a sample payload. So I just copied and pasted that into the source side and click Generate Target. ServiceNow did a whole bunch of parsing magic, and I have data pills for everything that the response might have. Now, some of you are looking at this and furiously writing me hate mail, because you remember that just a few slides ago, I set parameters to only look at some of the fields and not all of them. Then you look more closely and say, hey, you said you were querying the incident table, and that payload says the location table. And those fields aren't the same at all. And you are absolutely correct. Well done. So example payloads might not match your exact use case. And sometimes, you have to make a real request to get back a payload that you can use as a sample that's going to match what you're actually doing. How do you get that payload? Well, you test your flow. And when you run the test, you can look at the execution details. And you can scroll down a little bit and unfold the steps and then click on the response body. And that's going to give you the raw response of the actual API call that you made. So the system didn't know what to do with it, but it captured that you got a response. So I opened that up, copied and pasted into my parser step, clicked on Generate, and now I have a real payload for my API call with the exact fields that are going to get returned, and all of the types and everything else that I need to use for it. At this point, I just need to set up my action outputs. And then I can use this action in any of my flows. It's going to ask me as an input, please give me a sys ID. I can look that up from an existing record, if I'm saving those somewhere, or however else I'm going to get that input information. And then it's going to output those data pills with those values that I asked for. And that's it. You just made an action that's going to call an API and bring back useful data. And then continue on with your flow, and you can reuse this over and over again. Now, I know I went through a lot of stuff. And where do you go from here? I made a GitHub repo with some links to additional resources, the code that I used in this presentation, and other stuff that's going to help you as supplemental things to all of this. You can also feel free to find me on the #sndevs Slack. It is a wonderful community of developers, admins, and other ServiceNow professionals. It is a great place to go get help with whatever you need, talk to people, make connections. And again, if you have questions about this presentation, feel free to hit me up there. Did you like this session? I'm going to be doing it live in Las Vegas, and I would love to see you there. Thank you for watching. I hope that you found this useful and that you have a great time at Knowledge 22.