In my last Special Delivery post, I described the workflow for using the FileMaker Data API to push data from one database to another. I also promised to post more details in a new post. Let’s dig in to how this works.
I will warn you up front that this post is going to be a little technical. If you’re not a developer, or you don’t want to dig into the details of using the Data API, you might just want to look at it from a high level. On the other hand, if you are, then this should be enough to get you started. You can review the documentation for the Data API to get the details, but let’s recap the general process:
- Open a session to the target database on the server
- Create a new record with the data payload you want to send
- Close the session on the server
You can review the documentation for the Data API, but based on the three steps involved, it’s logical to have separate scripts for each step. Not only does this allow you to split the process up into logical chunks, it gives you building blocks that you can reuse for other calls. (This is especially true for the opening and closing of sessions.) So let’s look at step 1: Opening a session.
The general text for opening a session to a FileMaker database uses a URL (also called an endpoint) in this form:
[server domain name / IP address]/fmi/data/v1/databases/[database-name]/sessions
I suggest using a field to store the base endpoint (everything up to “sessions”). All of our solutions use a settings table with one record to store items of data just like this. Putting the URL in data means it’s easy to change without having to change the scripts in the solution.
The key to using the Data API from a FileMaker solution is to understand the somewhat unusual syntax embraced by FileMaker’s cURL (Command Line URL) implementation. Here’s a sample cURL call to open a session:
” -X POST” &
” –dump-header $responseHeader” &
” -H ” & Quote ( “Content-Type:application/json” ) &
” -H ” & Quote ( “Authorization: Basic [name:password as Base64]” ) &
” -d @$data”
The –dump-header call is optional; it captures the response header from the API so you can identify and trap errors that may come up (and believe me, errors DO come up when using an API!). A couple more points about the cURL syntax:
- The syntax of Quote ( “text in quotes” ) will usually produce something like this in FileMaker: “”text in quotes””. But because of the way the cURL call is processed, it works correctly.
- This is really weird syntax: “-d @$data”. $data is a variable. But inside quotes? Normally, if I put a variable declaration inside quotes, it comes out as a literal text string. But, FileMaker properly parses out the variable names for you.
- If you need to know what to store in $data, it’s an empty JSON object (“{}”). Don’t know why, but it’s a requirement of the API.
Once you’ve assembled the necessary precursors, the key to the whole operation is the Insert From URL script step. That’s what makes the call to the server. So our script looks like this:
Set Variable [ $data ; Value: “{}” ]
Insert From URL [ Select ; With dialog: Off ; $result ; $endpoint ; cURL options: (all the stuff above) ]
And it really is that simple. What you’ll receive back is a token in the $result variable, which will be a long string of letters and numbers. It comes back as part of a JSON object, so what we do is add another script step after the call:
Set Variable [ $token ; Value: JSONGetElement ( $result ; “response.token” )
That token is used throughout the session. Every call you make to the database from this point until you close the session requires it. So, we exit the script with that $token variable, thereby passing it back to the parent script.
Let’s move on to the call that actually pushes the data over. It’s a very similar process; you fetch the endpoint and then send the cURL data using Insert From URL. The URL for creating a new record looks like this:
[server domain name / IP address]/fmi/data/v1/databases/[database-name]/layouts/[layout-name]/records
As with other web implementations, FileMaker’s API is a layout-based system. So you’ll need to have one or more layouts for the tables you want to address. That layout will need to have all the fields on it you want to address with the API. (As an aside, you can omit fields you won’t need; this will help performance.) But the command to create a record then looks like this:
” -X POST” &
” –dump-header $responseHeader” &
” -H ” & Quote ( “Content-Type:application/json” ) &
” -H ” & Quote ( “Authorization: Bearer ” & $token ) &
” -d @$data”
In this case, $data is a JSON object that contains the data you want to push over. It’s passed as a series of name-value pairs inside an object called fieldData. The names are the field names (without the accompanying table); the values are, well, the values. So a sample data object might look like:{
{
“fieldData” :
{
“company” : “Net Caster Solutions”,
“firstName” : “Mike”,
“lastName” : “Mitchell”
}
}
If it’s successful, then the result will contain the recordID of the newly created record.
The last step in the process is to close the API session. Like I said in the previous post, this isn’t strictly required; FileMaker Server will close a session that hasn’t been used in the last 15 minutes. However, it’s a best practice to clean up after yourself. Closing a session is an API call to this endpoint:
[server domain name / IP address]/fmi/data/v1/databases/[database-name]/sessions/[token]
Once you call that endpoint (which includes the token of the session you want to close), you use a DELETE call to close the session:
” -X DELETE” &
” –dump-header $responseHeader” &
” -H ” & Quote ( “Content-Type:application/json” )
And that’s all there is to it. It looks like a lot of code, and it takes a bit of getting used to, but once you are used to it, it’s pretty straightforward. If you need help getting started, or you just have any questions, please don’t hesitate to contact us.
Happy FileMaking!
