[Music] today we're going to talk about scripted rest apis so what i have up here in my pdi is the scripted rest api table a scripted rest api is basically a web service that you can build and configure to allow external systems to talk to servicenow why would you do that well for one you may not have access to integration hub and there may come a time where the import sets or data sources provided to servicenow or even the endpoints directly to the tables are not robust enough or give too much access and you want to do something that you have more control over a scripted rest api is perfect for that for example if you ever come across web hooks if you want to subscribe to events in an external system maybe to generate tickets of some sort if you want to incorporate that web hook into service now uh scripted rest api is perfect for that you can process the json package or payload however you would like if you're dealing with some funky authentication you can handle it through scripting it's really versatile there are also instances where maybe you don't want to give important information or access to the entire table to an external system so you may want to curate the type of response that they're getting i know inbound web services for example the response that you get once you use that api is not extremely robust so maybe you want to give more information or maybe it's a get function and you just want to pass back certain fields and not give the whole table access you know there are multiple reasons you may want to use a scripted rest api but mainly what i use it for is when i need ultimate flexibility or i need to really tailor the response so for today's purposes i'm just going to use a simple example we have an external system that our managers use and every time somebody requests software they go in and check the reports to see if it's available in the first place so behind the scenes what that portal will do the portal is doing is just tapping into servicenow to check the model first if it exists if an entitlement exists for it and if one does to see if there are allocations available then it reports that number back so let's go ahead and build that api we're going to give it a name we're going to give it an api id this is auto populated based off the name if i want to give it something different i can the namespace is also auto populated this is derived from a property because this is global if it were any other scoped application the name space for that scope application would show here so i'm going to go ahead and save this and now you can see that the api id and the api namespace are both incorporated into the base api path so this is the endpoint that we're going to provide to external systems we need to add more to this endpoint in terms of specific resources that the endpoint can can use to get information from servicenow so let's go ahead and create a resource i'm going to give my resource a unique name because you could create as many resources as you want for your api really i'm going to call it get allocations it's going to be a get method and i'm going to fill out the rest of the endpoint path so when you call the same point we want to call get patience and also i want to pass in a variable which will be the model name that we'll be looking up so now it's time to write the script that will process either a payload or just the request from the the get call but i will point down here that we have some security so if you want to enforce authentication and enforce the acls you can use these check boxes i don't recommend unchecking these unless you plan to handle them in the script here above if you leave these unchecked then the endpoint is wide open to the internet and that is not a good idea so please leave these checked unless you plan to handle that in the script so let's go ahead and write this script the first thing i want to do is get the model get that using the request object there's also a response object you'll see and i'm going to get the path params and i know it's called model and i'm going to check if anything was sent and if not then i'm going to go ahead and return an error so now i'll use the response object to set an error this is one of servicenow's handy little error objects that they they provide to you i'm going to use a not found error provide my message no rl i'm going to set my status to 404 i'm going to return that will be the end of the script if no model is sent if i do have a model then we'll go ahead and query the entitlements table we're looking at the title we're going to add a simple query to see if the software model associated with this entitlement has the same name as the name that was sent in we're going to be looking at the display name we'll query that now if there's nothing there are no entitlements at all then we're going to return an error and it's going to be just like this one up here except let's use more specific error saying no entitlement oh all right and then if we do find entitlement or more let's get a count going so while we have those entitlements let's go ahead and account available let's get a positive response here let's set body to a json object where we return the count message of success there's our script let's go ahead and test this in the rest api explorer so if i come down here to explore the rest api it's going to take me to my endpoint that i just created so this would be the endpoint that you would provide to the external system they would have to pass in the model so let's go with adobe systems photoshop and let's test it out waiting for the response taking a while let me go back to my script real and save and all right so it's saved let's go ahead try that again this with adobe hit send depending on our response all right thing went through this time so if we look here we get a 200 response and yep we get a count and a message of success so if i enter something that's not in the system and hit send now we get our 4049 found and we get no entitlement with model whatever that is was found so it looks like we're working and that in a nutshell is a scripted rest api thanks for watching you