Published on April 23, 2020.

Yesterday I wrote about a project that I recently completed that involved integrating NetSuite with a ColdFusion-based system. I've also been working on a project that involves integrating ColdFusion with ServiceNow.

If you're not familiar with ServiceNow, it's a cloud-based platform that can be used to manage IT assets, IT services, and to create and manage digital workflows. ServiceNow is one of the most developer-friendly companies that I've ever encountered, and they generously provide a development instance at no charge. If you're a developer, go to https://developer.servicenow.com/ to learn more.

While working on this project, I developed a custom function that can be used to make calls to ServiceNow's Table API to retrieve records. I've found the function to be helpful, and thought I'd share it. My hope is that other developers, working on similar projects, will find it helpful as well.

Here's the function, and some sample code to show how you can use it.

<!--- ServiceNow Settings --->
<cfset sn_settings = structnew()>
<cfset sn_settings.account_id = "***SERVICENOW-ACCOUNT-ID***">
<cfset sn_settings.username = "***SERVICENOW-USERNAME***">
<cfset sn_settings.password = "***SERVICENOW-PASSWORD***">
<cfset sn_settings.table = "sys_user">

<!--- Example URL Params --->
<cfset url_params = structnew()>
<cfset url_params.active = "true">
<cfset url_params.sysparm_fields = "sys_id, first_name, last_name, phone, department, email, photo">
<cfset url_params.sysparm_query = "ORDERBYDESClast_name^ORDERBYfirst_name">
<cfset url_params.sysparm_limit = 10>
<cfset url_params.sysparm_display_value = "all">

<!--- Send the request to ServiceNow, and get the response. --->
<cfset response = get_from_servicenow( sn_settings, url_params )>

<!--- Dump the response. --->
<cfdump var="#response#">



<!--- Custom Function: get_from_servicenow --->
<cffunction
	name="get_from_servicenow"
	access="public"
	returntype="struct"
	output="true"
	hint="Sends a GET request to the ServiceNow Table API.">
	
	<cfargument
		name="sn_settings"
		type="struct"
		required="true"
		hint="The ServiceNow settings."
		/>   
		
	<cfargument
		name="url_params"
		type="struct"
		required="true"
		hint="The URL parameters to send."
		/> 
		
	<!--- Convert the URL Params to a string. --->
	<cfset url_params_string = "">
	<cfloop list="#structKeyList( url_params )#" index="param" >
		<cfif url_params_string != "">
			<cfset url_params_string = url_params_string & "&">
		</cfif>
		<cfset url_params_string = url_params_string & param & "=" & URLEncodedFormat( url_params[param] ) >
	</cfloop>	
	
	<!--- Create the full URL to send the request to. --->
	<cfset full_url = "https://" 
		& sn_settings.account_id 
		& "."
		& "service-now.com/api/now/table/" 
		& sn_settings.table
		& "?" 
		& url_params_string
		>  
	
	<!--- Send the HTTP request, and use basic authentication. --->
	<cfhttp
		url="#full_url#"
		method="get"
		result="http_response"
		authType="BASIC"
		username="#sn_settings.username#"
		password="#sn_settings.password#"
		>
		
		<!---<cfhttpparam type="header" name="Content-Type" value="application/json">--->
		<cfhttpparam type="header" name="Accept" value="application/json">  
		
	</cfhttp>		
			
	<!--- If the request was successfull... --->		
	<cfif http_response.statuscode eq "200 OK">	
		<cfset data = deserializejson( http_response.filecontent )>		 		
	<cfelse>
		<cfset data = structnew()>
	</cfif>
	
	<cfreturn data>
  
</cffunction>  

To call the custom function, pass it a structure with your ServiceNow information (account number, username, password, and the name of the table that you want to read from, and also pass a structure representing the URL parameters that you want to use in the request.

In the example, the request is for records in the Users (sys_user) table. I'm requesting active users, and only a few of the columns that are available (sys_id, first_name, last_name, phone, department, email, photo). I'm requesting that the records be returned in order by last name (descending), and sub-sorted by first name. And finally, I'm only requesting the first 10 records.

ServiceNow's Table API provides support for creating, reading, updating and deleting records. However, the custom function only supports reads - and specifically for filtering records. With a little work, you could modify the function to add support for create, update, and delete operations.

If you have any questions about the custom function, or need help with a ServiceNow integration project, please feel free to email me.