Using Postman Environments and Tests with the FileMaker Data API

/4 Comments/in , , , , , , /by

One of the new features of FileMaker Server 16 and FileMaker Cloud 1.16.0 is the FileMaker Data API – currently in trial mode which expires on September 27, 2018. The FileMaker Data API is an application programming interface (API) that allows web services to access data in hosted FileMaker solutions and conforms to Representational State Transfer (REST) architecture, making the FileMaker Data API a REST API.

You can use the Data API to integrate your FileMaker solutions with other applications and services – REST APIs are the current standard for integration and the Data API will be the replacement for the current XML and PHP APIs.

Your web service or application calls the FileMaker Data API to obtain an authentication token for access to a hosted solution, then uses that token in subsequent calls to create records, update records, delete records, and perform find requests.The FileMaker Data API returns data in JavaScript Object Notation (JSON), another standard that is used with REST APIs for data formatting (and is also supported by FileMaker Pro v16).

A great tool to use when testing REST calls with the Data API is Postman, a free app for macOS, Windows and Linux (paid versions are also available). Postman allows you to make requests (GET, POST, PUT etc) to a REST API like the FileMaker Data API and inspect the response, including the headers. You can quickly make changes to the requests and headers that you send and compare the results – when working with REST APIs a tool like Postman is indispensable.

As mentioned above the FileMaker Data API requires you to obtain an authentication token when first accessing a FileMaker solution – the access token is valid until you log out of a solution or for 15 minutes after the last call that specified the token. While the token is valid, each call that specifies the token resets the session timeout counter to zero. To save you from having to manually copy and paste your token with each new request you can use some features of Postman to save your from having to manually update any variables in your requests manually, including the Data API access token.

Postman lets you setup multiple “environments” that can contain multiple variables fore each environment, such as the host address URL. For example you might have a development environment and a production environment, each with their own host address and other variables. In Postman I would simply have a POST request URL like this:

https://{{server}}/fmi/rest/api/auth/Tasks

and in each Postman environment I would specify the value for the {{server}} variable. When you make your request by hitting the Send button in Postman it will insert the appropriate value for each variable you’ve specified. You can read all about setting up Postman environments and variables in the Postman docs.

As you can’t specify the Data API access token in advance you can use another great feature of Postman to dynamically create the token variable which is then used in subsequent API requests. Your initial request to authenticate/login will look like this:

{ "user":"admin", "password":"admin", "layout":"Tasks" }

and if successful the response will look like this:

{ "errorCode": "0", "layout": "Tasks", "token": "fdde29fa175eb1cc8347512ca327b191619fc32ed65efaab26d8" }

Using the Tests feature when making a Postman request you can execute some JavaScript code after the request is sent to dynamically create a token variable that you can use with your subsequent API calls without having to copy and paste the token each time. Here’s a screenshot of how you would set this up in Postman for the Data API authentication request:

The JavaScript code you can copy/paste is:

var data = JSON.parse(responseBody);
postman.setEnvironmentVariable("token", data.token)

Using Postman environments and Tests to update the token variable makes working with the FileMaker Data API much easier and should save you a lot of time.

Voice Calling with FileMaker

/3 Comments/in , , , , , , , /by

Since we released v1 of fmSMS many years ago we’ve been approached by customers from all around the world to work on integrations between FileMaker and other APIs (Application Programming Interfaces). Customers love using FileMaker to send and receive SMS/TXT messages, but they have also asked us to help them send faxes, MMS/Picture messages and to make outgoing voice calls from their FileMaker solution.

We’ve done a number of voice call integrations with FileMaker over the years – having FileMaker initiate a series of outgoing voice calls can be useful in a number of situations, including:

  • Alerts: you might not have mobile phone numbers for all your contacts/customers, but if you have a phone number you can call that number to provide an update to important events (e.g. school closures due to snow days)
  • Election Campaigns: we’ve helped one customer initiate a series of campaign calls to voters about upcoming elections (you may well have been on the receiving end of one of these)
  • Appointment Reminders: we helped one customer move away from having administration staff manually phone each customer about their upcoming appointments and having FileMaker generate these calls, saving them 1-2 hours of staff time each day

The process for generating a voice calling campaign works as follows:

  1. you’ll need to sign up for an account with one of the voice calling providers such as Twilio that handle the voice calling
  2. if you wish to have a dynamically generated message that references data from your FileMaker solution (e.g. to have the voice call say “Hello Andrew” instead of just “Hello”) you’ll need a process on your FileMaker Server than can generate the dynamic message for each contact to be called. We use the FileMaker API for PHP to generate these. If you don’t need a dynamic message you could simply hard code the message so it is the same for all recipients of the voice call
  3. a FileMaker script that is initiated either by a user or FileMaker Server that finds a group of records, then loops through each record and makes a request to the voice calling provider to generate a new outgoing call to that contact
  4. if you wish to be notified of the result of each call you can setup a webhook on your server to be notified by the voice calling provider each time a call is made with the result (engaged, answered etc) and the duration of the call

We’ve put together a simple demonstration video showing this in action – you can watch the video inline below or directly on YouTube:

 

If you would like to discuss integrating voice calling into your FileMaker solution please get in touch.

FileMaker and eCommerce Integration – Part 3

/1 Comment/in , , , , , , , , , , /by

puzzle-1152793_1280

In Part 1 of our series on FileMaker and eCommerce Integration we outlined the challenges many small businesses face when they go live with an online store and the new workflow challenges that can create, leading to the prospect of having to do double data entry in multiple places. In Part 2 we showed how you eliminate any double data entry by making your online store visible to your FileMaker solution by using the ESS (External SQL Data Sources) feature of FileMaker Pro/Server, allowing users to see online orders on a normal FileMaker layout.

Not all FileMaker Pro solutions will be able to take advantage of the ESS feature however for a variety of reasons, including:

  • your online store doesn’t use a supported ESS data source
  • your online store hosting provider doesn’t allow remote SQL access
  • your company firewall won’t allow ESS access to the hosting provider
  • you wish to avoid the expense of purchasing ODBC drivers

There are a number of alternatives to having a “live” view of your online orders using ESS which can be broadly defined as either a push or pull approach, whereby data is either pushed from the online store to your FileMaker solution or pulled/downloaded from your online store by your FileMaker solution. Like all solutions there are pros and cons to each approach and the particulars of how your FileMaker solution is hosted will determine which options are available to you.

In the following examples we’re going to be using the WooCommerce plugin for WordPress as it offers both a push and pull API and is a popular eCommerce store, powering over 37% of all online stores at the time of writing.

Push Online Orders to FileMaker – the push approach is usually considered the most optimal solution as it is only invoked when there is new data to transfer, thus reducing the number of unnecessary requests to the online store to check for new orders. In WooCommerce you implement a push solution through the use of Webhooks – Webhooks are are very common form of server event notifications which trigger an action by sending a request to a URL that you specify. WooCommerce has a number of Webhooks that you can activate, for example each time a new order is created.

We’ve helped many customers over the years implement a Webhook solution that works as follows:

  • a new order is created on the customer’s online store
  • a Webhook is triggered which sends the details of the new order as JSON encoded data to a URL (a PHP page) on the customer’s FileMaker Server
  • the PHP file uses the FileMaker PHP API to convert the JSON encoded data into a new customer record, order record and order line items

The customer also receives an email for each new order, which prompts them to open their FileMaker database and review the order details and ship any required products then push the invoice to their accounting software (Xero, MYOB etc). The customer hasn’t had to do any double data entry or query the online store for new orders – everything is pushed through as it happens. It does require the customer to have FileMaker Server with Custom Web Publishing enabled and allow external access to the PHP file hosted on their server.

Pull Online Orders to FileMaker – if the push approach is not a viable option WooCommerce also offers a REST API that you can also use with FileMaker Pro. The WooCommerce REST API allows you to query your WooCommerce online store and retrieve details about customers, orders, products etc, as well as being able to push data from FileMaker to WooCommerce if necessary. A typical solution using the WooCommerce REST API works as follows:

  • customer receives an email notification from the WooCommerce store about a new order
  • customer then clicks a button in their FileMaker solution to query the online store for any new orders since a timestamp (typically the last time they checked for new orders)
  • FileMaker sends a REST API request for any new order details and receives a JSON encoded response from the WooCommerce REST API with details about each order
  • the response is parsed out to create new customer, order and order item records

Once again the customer has been able to eliminate any double data entry and simply has to click a button in FileMaker to get all the new order details.

As we have illustrated in this series there are typically a number of options available when it comes to integrating your online store with your FileMaker CRM, whether that’s a direct live view using ESS or having new orders pushed or pulled into your FileMaker solution. With an integration into your accounting software such as Xero, MYOB AccountRight or MYOB Essentials you can completely eliminate any double data entry for the entire order and sit back and watch as the data flows from your online store to FileMaker and then to your accounting software.

If you would like to discuss integrating your online store with your FileMaker CRM please get in touch for a free initial consultation.

FileMaker and eCommerce Integration – Part 1

FileMaker and eCommerce Integration – Part 2

FileMaker and eCommerce Integration – Part 3

FileMaker Pro 13 – HTTP POST and HTTP Headers

/5 Comments/in , , , , /by

In FileMaker Pro v13 you can now perform an HTTP POST when importing XML data or using the “Insert from URL” script step. Both HTTP GET and HTTP/S POST are supported – GET and POST are generally the 2 most popular HTTP Request Methods when working with web services.

FileMaker Pro v12 already supported HTTP GET so nothing has changed here – you only need to specify the URL to perform an HTTP GET request. To perform an HTTP POST request you need to specify a URL starting with either:

  • httppost
  • httpspost

You then include a “?” character in the URL to separate the request URL from the POST data. Everything before the first “?” character is the request URL and everything after the first “?” character is the post data. For example to query a web service that converts Fahrenheit to Celsius you would use the following URL:

httppost://www.w3schools.com/webservices/tempconvert.asmx/FahrenheitToCelsius?Fahrenheit=100

FileMaker Pro recognises that you wish to perform an HTTP POST by the use of “httpost” at the beginning of the URL. The URL for the HTTP POST then becomes everything up to the first “?” character:

http://www.w3schools.com/webservices/tempconvert.asmx/FahrenheitToCelsius

and the POST data is everything after the first “?” character:

Fahrenheit=100

We get an XML result like this:

<?xml version=”1.0″ encoding=”utf-8″?><string xmlns=”http://www.w3schools.com/webservices/”>37.7777777777778</string>

which we could easily parse using FileMaker functions to get the actual Celsius value into a FileMaker field (see Demo File link at the bottom).

HTTP Headers

One of the main limitations when performing an HTTP POST is that we are unable to set the HTTP Headers. When working with web services – particular SOAP/XML based web services – you will often be required to set specific headers before sending the HTTP POST data. With FileMaker Pro 13.0v1 the following headers are set automatically and cannot be changed:

User-Agent: FileMaker/13.0

Content-Type: application/x-www-form-urlencoded

Hopefully a future update to FileMaker Pro will allow developers to set the HTTP Headers for each request – in the meantime you will have to continue using of the available FileMaker plugins (such as the BaseElements plug-in)

 

HTTP POST Demo.fmp12