Published on May 4, 2020.

A few weeks ago, I wrote about two ColdFusion projects that I've recently worked on. One of those projects involved integrating with NetSuite, and the other involved integrating with ServiceNow.

Shortly after that last post, I was contacted by a customer requesting a similar integration. This project involved a FileMaker / ColdFusion integration solution.

For years they've been integrating a FileMaker database (that had been developed for their HR department) with a mission-critical ColdFusion-based Web portal. The ColdFusion app pulls employee data from FileMaker by sending an employee's ID.

The integration had been using the FileMaker API for PHP, and it's been working perfectly. However, the customer is concerned that at some point the older API might be deprecated or removed. Therefore, to future-proof the integration, they wanted to update the app so that it uses the newer FileMaker Data API.

I approached this project in much the same way that I did the previous ColdFusion integration projects. I created three ColdFusion custom functions. One function handles logging into the database (getting an authorization token), another function processes API requests (performing finds, etc), and the other function closes the FileMaker session (by logging out).

Here are the functions, and some sample code to show how you can use them.

<!--- FileMaker Settings --->
<cfset fm_settings = structnew()>
<cfset fm_settings.protocol = "https">
<cfset fm_settings.database_host = "***FILEMAKER-HOST***">
<cfset fm_settings.database_name = "***FILEMAKER-DATABASE***">
<cfset fm_settings.account_name = "***FILEMAKER-ACCOUNT-NAME***">
<cfset fm_settings.password = "***FILEMAKER-PASSWORD***">

<!--- Example Request --->
<cfset http_method = "POST">
<cfset url_extras = "/layouts/employees/_find">
<cfset payload = structnew()>
<cfset payload.query = arraynew( 1, false)>
<cfset payload.query[1] = structnew()>
<cfset payload.query[1].employee_uuid = "d37cb9f9-6969-4c88-b487-f690ab1aaf14">
<cfset payload.limit = 1>

<!--- Send the login request and get the token. --->
<cfset token = fm_login( fm_settings )>

<cfset find_response = fm_request_send( fm_settings, token, http_method, url_extras, payload )>
<cfdump var="#find_response#">

<!--- Send the logout request. --->
<cfset logout_response = fm_logout( fm_settings, token )>



<!--- Custom Function: fm_login --->
<cffunction
	name="fm_login"
	access="public"
	returntype="string"
	output="true"
	hint="Sends a request to the Data API for a token.">
	
	<cfargument
		name="fm_settings"
		type="struct"
		required="true"
		hint="The FileMaker database connection settings."
		/>   
	
	<!--- Create the full URL to send the request to. --->
	<cfset full_url = fm_settings.protocol 
		& "://" 
		& fm_settings.database_host 
		& "/fmi/data/vLatest/databases/" 
		& fm_settings.database_name
		& "/sessions" 
	>
		
	<!--- Create the Authorization header value. --->
	<cfset auth = "Basic " & ToBase64( fm_settings.account_name & ":" & fm_settings.password )>
		
	<!--- Send the HTTP request, and use basic authentication. --->
	<cfhttp
		url="#full_url#"
		method="post"
		result="http_response"
	>	

		<cfhttpparam type="header" name="Authorization" value="#auth#">
		<cfhttpparam type="header" name="Content-Type" value="application/json">

	</cfhttp>
	
	<!--- If the request was successfull... --->		
	<cfif http_response.statuscode eq "200 OK">	
	
		<!--- Deserialize the JSON-encoded response. --->
		<cfset data = deserializejson( http_response.filecontent )>		 
		
		<!--- Get the token. --->
		<cfset token = data.response.token>				
		
	<cfelse>
		<cfset token = "">
	</cfif>
	
	<cfreturn token>

</cffunction> 


<!--- Custom Function: fm_logout --->
<cffunction
	name="fm_logout"
	access="public"
	returntype="struct"
	output="true"
	hint="Ends a FileMaker session.">
	
	<cfargument
		name="fm_settings"
		type="struct"
		required="true"
		hint="The FileMaker database connection settings."
		/>   
		
	<cfargument
		name="token"
		type="string"
		required="true"
		hint="The token associated with the session."
		/>  		
	
	<!--- Create the full URL to send the request to. --->
	<cfset full_url = fm_settings.protocol 
		& "://" 
		& fm_settings.database_host 
		& "/fmi/data/vLatest/databases/" 
		& fm_settings.database_name
		& "/sessions/" 
		& token
	>
		
	<!--- Create the Authorization header value. --->
	<cfset auth = "Basic " & ToBase64( fm_settings.account_name & ":" & fm_settings.password )>
		
	<!--- Send the HTTP request, and use basic authentication. --->
	<cfhttp
		url="#full_url#"
		method="delete"
		result="http_response"
	>	

		<cfhttpparam type="header" name="Authorization" value="#auth#">
		<cfhttpparam type="header" name="Content-Type" value="application/json">

	</cfhttp>
	
	<!--- If the request was successfull... --->		
	<cfif http_response.statuscode eq "200 OK">	
	
		<!--- Deserialize the JSON-encoded response. --->
		<cfset data = deserializejson( http_response.filecontent )>		 		
		
	<cfelse>
		<cfset data = structnew()>
	</cfif>
	
	<cfreturn data>

</cffunction> 



<!--- Custom Function: fm_request_send --->
<cffunction
	name="fm_request_send"
	access="public"
	returntype="struct"
	output="true"
	hint="Sends a request to the Data API.">
	
	<cfargument
		name="fm_settings"
		type="struct"
		required="true"
		hint="The FileMaker database connection settings."
		/>   
		
	<cfargument
		name="token"
		type="string"
		required="true"
		hint="The token assigned to the session."
		/>  	
		
	<cfargument
		name="http_method"
		type="string"
		required="true"
		hint="The HTTP method (http, https) to use when sending the request."
		/>  		
		
	<cfargument
		name="url_extras"
		type="string"
		required="true"
		hint="Any additional URL path / params to append to the base URL."
		/>  	
		
	<cfargument
		name="payload"
		type="struct"
		required="false"
		hint="The JSON-encoded payload to send."
		/>  				
	
	<!--- Create the full URL to send the request to. --->
	<cfset full_url = fm_settings.protocol 
		& "://" 
		& fm_settings.database_host 
		& "/fmi/data/vLatest/databases/" 
		& fm_settings.database_name
		& url_extras
	>
	
	<!--- Convert the payload from a structure to a JSON-encoded string. --->
	<cfset payload = serializeJSON( payload )>	
			
	<!--- Send the HTTP request, and use basic authentication. --->
	<cfhttp
		url="#full_url#"
		method="#http_method#"
		result="http_response"
	>	

		<cfhttpparam type="header" name="Authorization" value="Bearer #token#">
		<cfhttpparam type="header" name="Content-Type" value="application/json">
		<cfhttpparam type="body" value="#payload#">

	</cfhttp>
	
	<!--- If the request was successfull... --->		
	<cfif http_response.statuscode eq "200 OK">	
	
		<!--- Deserialize the JSON-encoded response. --->
		<cfset data = deserializejson( http_response.filecontent )>		 		
		
	<cfelse>
		<cfset data = structnew()>
	</cfif>
	
	<cfreturn data>

</cffunction> 

I hope that you find these ColdFusion functions helpful.