API Primer for FileMaker

What is an API and why should you care? APIs are the means by which your FileMaker solution can access all kinds of services and interface with other data stores. When you get a little understanding of this, the world of systems integration really opens up for you.

API stands for Application Program Interface. It is the interface by which an application accesses a service. It essentially provides an interpreter service translating requests into language the service can understand and returns the results requested. It means that the service can be treated as a black box – requests go in, unseen magic happens, and results come out.

The Restaurant

An analogy may be useful. You are a customer (application) seated at a restaurant. You are hungry and would like to eat, so you peruse the menu and decide on a steak.

Waiter taking an order (API receiving request)

You can’t go into the kitchen and cook it yourself or direct the chef to cook it for you. Instead, a waiter (API) takes your order. He or she interprets your specific requirements such as wanting it cooked medium-rare and serving the sauce on the side. The waiter then communicates the order to the kitchen (service) in a manner understood by them. The kitchen staff prepare the meal and ring a bell when it is ready.

Neither you nor the waiter know how it was done. Your meal is delivered to your table as ordered.

The reverse can happen when it comes to pay for your meal – the restaurant becomes the application requesting a result (payment) from you.

API Services

In our case, we are interested in accessing external services from our FileMaker solution. This may be to simply push or pull data, or to manipulate data for us.

Examples of services we may use:

  • send a text message by SMS
  • submit invoice data to an accounting application
  • retrieve the English version of some foreign language text
  • submit an ISBN to get all the data about a book
  • verify a credit card for processing

A lot of the services fit into the category of ‘not reinventing the wheel’ – it is far easier and more robust to access a service that is designed expressly for purpose, then to try to build and maintain it yourself.

Making an API Request

The basics of any API transaction are similar:

  1. establish identity and authority to make a request
  2. make the request providing data in the required format
  3. receive a result

Sometimes the result is as simple as ‘OK’. Sometimes it is a stream of data.

Example – Sending an SMS

In this example, we will send an SMS text message from a FileMaker database to a given mobile (cell) number using a service called ClickSend. ClickSend have a number of APIs – the one we will be using is their REST API – by their description it is the “Latest most powerful API with JSON request and response.”

1. Authorisation

To use the API, you need to create a free account. This sets you up with an API username and API key. These are used to authenticate yourself to use the service. It also authorises the service to use credits in your account to send SMS messages.

My username is davidhead and my API Key is of the form 5AF333BF-0D51-617D-4586-A1B1188006XX (not my real key).

The Authorization header is constructed by combining username and password as a string – username:password. This is encoded using Base64 encoding and the authorisation method and a space is put before the encoded string. Using the above username and key, you will get:

Authorization: Basic ZGF2aWRoZWFkOjVBRjMzM0JGLTBENTEtNjE3RC00NTg2LUExQjExODgwMDZYWA==

Side Note: if you use the FileMaker function Base64Decode on the encoded text, you will see the original username and key separated by a colon.

2. Make the Request

The ClickSend API documents for “Send SMS” detail the structure of the request including what data is required and in what format.

The HTTP request is a POST – data is being sent to the service. Another common method is GET – to request data from a resource.

The content is supplied in JSON format. A single message has a number of possible properties:

  • source – method of sending e.g. php
  • from – the mobile number that will show as the sender
  • body – the text message to be sent
  • to – the mobile number of the recipient
  • schedule – an optional time code to schedule sending of the message
  • custom string – your reference for the message

In FileMaker Pro, the request is made with a script step Insert From URL. In that script step, we can specify the URL to call, any options to be sent with the call, and the target for the result (a field or a variable).

The URL we call is known as an endpoint. The API documents tell us the base URL and the endpoint for each service. For the current ClickSend API, the base URL is https://rest.clicksend.com/v3/ and the endpoint for the Send SMS service is sms/send. So the URL we will send to is https://rest.clicksend.com/v3/sms/send

The options sent with the request are cURL options. These are the request type (POST), an authorisation header (encoded in Base64 as above), a content header (saying the content is in JSON format), and the message properties structured in JSON.

3. Receive a Result

The result is received back into the target defined in the Insert from URL script step. This may be a field or a variable. For the ClickSend API, the result is returned in JSON format. It contains a copy of all the data supplied as well as sending information such as message_price (0.077), status (SUCCESS), http_code (200), and more.

The result can be parsed into a FileMaker record to save the result of the message send operation.

Conclusion

This has been a brief primer on the use of an API in your FileMaker solutions. In this article, we have only considered one example of an API request from FileMaker. FileMaker Server also provides a Data API. This can be accessed by external services to push data into and pull data from FileMaker solution hosted by FileMaker Server.

Can we help?

Do you need assistance finding an API or integrating it into your FileMaker solution? Or do you just want to discuss the range of possible options for accessing the myriad of API services out there? We are here and ready to help you. Contact us today.


FileMaker Training – Singapore 2019

We have just scheduled FileMaker training courses in Singapore in March 2019. Our FileMaker courses are hands-on with small class sizes. They put you on the fast track in FileMaker development. If you, or someone you work with or know, would like to become a better FileMaker developer, have a look at the course schedule now.

All courses listed below are currently open and are subject to minimum enrolments before they can be confirmed.

When you enrol, you will pay a holding deposit. This is non-refundable except if the course does not run. In that case, you will be notified and the holding deposit will be refunded in full.  The decision to run the courses will be made by 12 February. If the course is confirmed, you will be asked to enrol using a coupon code which will provide an additional $100 discount.

Get Started with FileMaker Pro

This introductory course is scheduled for 11-12 March 2019 (Tuesday-Wednesday).

Get Started with FileMaker Pro is an introduction to FileMaker Pro and creating custom database solutions. It covers everything from creating a new solution, setting up data structure, customising the appearance, securing and deploying your file and more.

Check the full course outline and book here.

Building Effective FileMaker Solutions

This intermediate course is scheduled for 13-14 March 2019 (Thursday-Friday).

Building Effective FileMaker Solutions is an intermediate course in FileMaker development. We briefly review FileMaker components and then dive into how they really work. The course covers development methods and habits, and a deep look at systems analysis and data structure for better outcomes. Over the two days, we cover many examples of calculations, scripting, security and user interface design. 

Check the full course outline and book here.

FileMaker Scripting in Depth

We are also offering an advanced course in FileMaker scripting, scheduled for 18-19 March 2019 (Monday-Tuesday).

FileMaker Scripting in Depth is an advanced course in FileMaker development. We will cover all aspects of script editing, management and use. The course covers scripting methods using various classes of script steps. Over the two days, we cover many examples of scripting that will be useful in your FileMaker development. 

The full course outline is available here and you can book here.

Training Courses – Brisbane, Sydney, Melbourne

We currently have confirmed courses running in Brisbane, Sydney and Melbourne. This means that you can plan your time with confidence knowing that the course will run.

Our training courses give you the fast track in FileMaker development. If you, or someone you work with or know, would like to become a better FileMaker developer, have a look at the course schedule now.

Get Started with FileMaker Pro

This introductory course is scheduled and confirmed in:

  • Melbourne 1-2 November 2018
  • Brisbane 8-9 November 2018

It is also open on the schedule for Sydney 28-29 November 2018.

Check the full course outline here and book here.

Building Effective FileMaker Solutions

This intermediate course is scheduled and confirmed in:

  • Brisbane 18-19 October 2018
  • Sydney 29-30 October 2018

It is also open on the schedule for Melbourne 11-12 December 2018.

Check the full course outline here and book here.

NEW: FileMaker Scripting in Depth

We are also offering a new advanced course in FileMaker scripting. The full course outline is available here. And the schedule is open for:

  • Sydney 3-4 December 2018
  • Melbourne 13-14 December 2018

FileMaker Solution: logging usage – Part 2

At uLearnIT, we love solving your problems. Here is Part 2 of the latest problem solved for a client using our mentoring services. If you missed Part 1, it is here.

Request

In an existing FileMaker solution, we would like to know if certain scripts and layouts are being used. Over the years, the solution has been added to and updated in a haphazard manner and we would like to clean it up. How can we find out which scripts and layouts are in use?

Solution

From Part 1, the key to this solution is to automatically log the use of scripts and layouts by triggering a script. The script will record the name of the layout or script used and then create a log record. The log record will be created in a special table for the purpose.

Script use

The script to log script use will be called at the start of each script – using the Perform Script script step. It will pass the currently running script name as a script parameter that will be entered into a log record. To set up the script step in any script:

  1. Open the Script Workspace and open a script.
  2. Add the script step Perform Script to the start of the script.
  3. Specify the Log script use script.
  4. Set the Optional script parameter to Get ( ScriptName )
Perform Script with script selected and script parameter defined

The script used to Log Script Use is as follows:

New Window [ Style: Card; Using layout: “uselog” (uselog); Height: 100; Width: 100; Top: 0; Left: -1000; Dim parent window: No ]
New Record/Request
Set Field 
[ uselog::name; Get ( ScriptParameter ) ]
Set Field [ uselog::item; "script" ]
Close Window [ Current Window ]

In the script above, the operation is performed in a card window off the user screen. This ensures that it does not interfere with the user’s normal actions or that of any running script. Since the parent screen does not dim, the user should not notice the script run. 

The script creates a new card window and goes to a layout to create a new log record. It uses Set Field script steps to set the name field with the script parameter (in this case the script name), and the item field with the text string script.

Add the Perform Script step (simply copy and paste between scripts) to every script for which you want to log use. Over time as the solution is used, the log records build an account of script use. This can then be analysed to see which script are most commonly used and which scripts are rarely or not used.

Addendum

A suggestion tweeted by @tonywhitelive was to also record Script Parameter, File Name and Layout Name when logging scripts. 

The file name would be useful when logging scripts running outside of the file where the log record exists. The script parameter and the layout name will provide some useful data about how and where the script was triggered.

So we will need to add three more fields to the log record – parameter, file, layout. And then adjust the script logging script to unpack and apply the various values.

When calling the new script, the parameter will use the List function to capture multiple pieces of data as a list of values:

List ( Get(ScriptName); Get(FileName); Get(LayoutName); Get(ScriptParameter) )

These values can then easily be unpacked when received using the GetValue function.

Parameter values unloaded into variables and then used to populate log fields

So there you have it – even more functional script use logging. Thanks Tony!

Do you need uLearnIT to solve a problem?

We can do the same for you. Just let us know what you are struggling with and we will provide a cost effective solution. We have saved our customers hours of Googling answers and frustration trying things that never worked for them.

We can do the same for you.

Contact us now before you waste any more time!

FileMaker Solution: logging usage – Part 1

At uLearnIT, we love solving your problems. Here is the latest one solved for a client using our mentoring services.

Request

In an existing FileMaker solution, we would like to know if certain scripts and layouts are being used. Over the years, the solution has been added to and updated in a haphazard manner and we would like to clean it up. How can we find out which scripts and layouts are in use?

Solution

It is unreliable and unwieldy for users to manually log their usage. Often, they do not know which scripts and which layouts they use. If they report the use of buttons, then they also have to report which screen and then the developer has to decipher the use.

The key to this solution is to automatically log the use of scripts and layouts. This can be done by triggering a script. The script will need to record the name of the layout or script used and then create a log record. The log record will be created in a special table for the purpose. The log record will have fields for:

  • item (type) – layout or script
  • name – of the layout or script
  • account – name of the account currently in use
  • creation – timestamp when created

The item will be set by the script; name will come from the script parameter; account and creation will be auto-entered.

Layout use

The script to log layout use will be triggered OnLayoutEnter – after a layout is loaded. It will pass the layout name as a script parameter that will be entered into a log record. To set this trigger for any layout:

  1. Navigate to the layout and enter Layout mode.
  2. Select Layouts > Layout Setup… and then Script Triggers.
  3. Select the OnLayoutEnter event and select the required script.
  4. Set the Optional script parameter to Get ( LayoutName )
Layout Setup – Script Trigger configuration

The script used to Log Layout Use is as follows:

New Window [ Style: Card; Using layout: “uselog” (uselog); Height: 100; Width: 100; Top: 0; Left: -1000; Dim parent window: No ]
New Record/Request
Set Field 
[ uselog::name; Get ( ScriptParameter ) ]
Set Field [ uselog::item; "layout" ]
Close Window [ Current Window ]

In the script above, the operation is performed in a card window off the user screen. This ensures that it does not interfere with the user’s normal actions or that of any running script. Since the parent screen does not dim, the user should not notice the script run. 

The script creates a new card window and goes to a layout to create a new log record. It uses Set Field script steps to set the name field with the script parameter (in this case the layout name), and the item field with the text string layout.

Repeat the layout script trigger for every layout for which you want to log use. Over time as the solution is used, the log records build an account of layout use. This can then be analysed to see which layouts are most commonly used and which layouts are rarely or not used. 

Use log for layout items

See Part 2 for scripts…

In Part 2 of this post, we will look at how to log the use of scripts in a solution. It is a simple extension of the above method for layouts.

Do you need uLearnIT to solve a problem?

We can do the same for you. Just let us know what you are struggling with and we will provide a cost effective solution. We have saved our customers hours of Googling answers and frustration trying things that never worked for them.

We can do the same for you.

Contact us now before you waste any more time!

FileMaker Solution: entering partial dates

At uLearnIT, we love solving your problems. Here is the latest one solved for a client using our mentoring services.

Request

In our Equipment table there is a field for DOM (date of manufacture). It is defined as a text field since the data is just a month and a year such as 03/10 or 11/15. We would prefer the service techs to enter the data as written. We don’t want them rejecting the process because it’s uncomfortable.

But then we need to perform simple calculations on the DOM. For example,  if the DOM is more than 5 years past, a “Level 4” service is due.

Solution

Part 1: Data Entry

It would be great to allow users to enter a month and year as the DOM in a number of ways. So let’s allow them to enter say March 2015 as any of 315, 0315, 3/15 or 03/15. And then reset the data on field exit to the standard 03/15. 

This is done with a field option which is an auto-entered calculation. Importantly, the option Do not replace existing value of field (if any) was unchecked – so that the calculation is evaluated when leaving the field.

Case ( 
Length ( Self ) = 3;
"0" & Left (Self; 1) & "/" & Right (Self; 2);
PatternCount (Self ; "/") and Length (Self) = 5;
Self;
PatternCount (Self ; "/") and Length (Self) = 4;
"0" & Self;
Length ( Self ) = 4;
Left (Self; 2) & "/" & Right (Self; 2);
"Error"
)

In this Case statement, there are four tests:

  1. if the length of the data is 3 characters, then add a leading zero and insert a slash character – so 315 becomes 03/15
  2. if there is a slash and the length is five characters, then leave as is – so 03/15 would be left as is (returns Self)
  3. if there is a slash and the length is four characters, then add a leading zero – so 3/15 becomes 03/15
  4. if the length is four characters, then insert a slash in the middle – so 0315 becomes 03/15

And if all those tests fail, it returns the result “Error”. That may happen if you enter 35 or 032015. 

Exceptions could be handled in other ways but it was not needed here.

Part 2: Calculate a proper date

Now that we have some standard data to work with, we can easily convert that into a proper date with a calculation. The decision was made to standardise on the first of the month.

So we set up a calculation field (DOM as date) using the expression:

Let ([
raw = DOM; // the field entered as MM/YY
themonth = GetAsNumber (Left (raw ; 2));
theyear = GetAsNumber (Right (raw ; 2));
theyear = theyear + 2000 - If(theyear >50; 100);
// convert to four digit
thedate = Date (themonth ; 1 ; theyear)
// date of first of month ]; thedate )

The process in the Let statement is:

  1. The field (DOM) is set into a variable called raw.
  2. Then raw is processed to get the month and the year – first and last two characters respectively. 
  3. Then the month and year are used to get the date of the first day of the month.
  4. The year is converted into four digits.
  5. The Let function returns the proper date (calculation result type is date)

QED

So that is the simple solution that lets techs enter the date quickly and easily, and then use it to move forward into other calculations to work out service requirements and more.

Do you need uLearnIT to solve a problem?

We can do the same for you. Just let us know what you are struggling with and we will provide a cost effective solution. We have saved our customers hours of Googling answers and frustration trying things that never worked for them.

We can do the same for you.

Contact us now before you waste any more time!

Prepare for FileMaker Developer Certification – now in Melbourne

Due to popular demand, the Prepare for FileMaker Developer Certification has been moved to a Melbourne CBD location.

The course is an intensive advanced level course designed to prepare candidates for the Developer Essentials for FileMaker 16 exam. The course covers all knowledge areas of the exam paying attention to the approximate weighting for each.

When and Where

It runs for two full days – Mon 25 & Tue 26 September 2017. The location has not yet been finalised but will be in the Melbourne CBD and likely to be at Ether Conference Venue at 265 Little Bourke St, Melbourne.

The course cost is AU$1190 but there is an Early Bird Special – AU$990 – running until 31 August 2017.

So get in now to book your place and save $200.

WHO SHOULD ATTEND?

This course is designed for people preparing to sit the Pearson VUE exam to achieve the certification as FileMaker 16 Certified Developer. The course does not aim to teach you about FileMaker development per se, but to look at what should be the knowledge and skills of a competent FileMaker developer across the entire FileMaker Platform. To gain the most from the course, you should have hands-on experience developing and deploying recent FileMaker solutions including installation, configuration and maintenance of FileMaker Server.

Course Details and Booking

For more details and to book online, please go to our Training Schedule page.

Get FileMaker 16 Developer Certification

Are you a FileMaker Certified Developer?
Why should you care? Why should your customers care?
How do you study for the Certification exam?

FileMaker Inc., has released the Developer Certification exam for the FileMaker 16 Platform. In their words:

“This credential demonstrates to clients, peers and management that you have achieved an essential level of knowledge, experience, and skills in developing on the FileMaker Platform.”

Candidates who pass the exam receive the FileMaker 16 Certified Developer credential.

Why get Certified?

This is the only industry certification available for FileMaker developers. While it does necessarily mean you are a great developer, it does give you the best chance of being great. Passing the exam means that you have a competent level of knowledge of the FileMaker Platform.

FileMaker Inc., lists the benefits of Developer Certification. These include:

  • Expand your FileMaker developer skill set
  • Stay up-to-date on current FileMaker technologies
  • Increase your credibility (“dev cred”)
  • Promote yourself with the FileMaker Certification logo
  • Preferred listing on the FileMaker website (FBA only)

How do you prepare for the exam?

There is an exam study guide provided on the FileMaker web site. FileMaker recommend “at least 6 months of development experience with the FileMaker Platform before attempting the exam”.

While there is nothing better than hands-on experience with FileMaker products, many people still struggle with what to study and how to study in each of the areas identified. The exam covers areas where you may not have had any practical development experience. So what do you need to know?

Do a Certification Preparation course

uLearnIT is seeking expressions of interest from people to attend a Certification Preparation course. This course is written and presented by David Head. He is a Certified Developer in every version of the FileMaker Platform beginning with version 7.

David has successfully run this course for previous FileMaker versions. Many people attending not only passed the exam, but also recognised benefits in how they approach and develop their FileMaker solutions.

The course does not “teach to the exam”. David covers materials that will be in the exam and also material that will not (but probably could be). He presents material from the point of view of “why is this important to a FileMaker Developer?”. The presentations and exercises will make you question your ideas about FileMaker products. You will think more about how they work and why they behave the way they do.

Example

For example, when a FileMaker script is run with Full Access privileges, does that present any security risk? Can a user get access to parts of the solution that they should not? How do this feature actually work? What Get functions are affected by running a script in this way?

The course is a series of intense study sessions over consecutive days. There is a combination of theory and group exercises. Group discussion should challenge your ideas about how FileMaker works.

You will think about content from the point of view of what is important and what you really need to know. The exercises will give you skills to go and investigate parts of FileMaker in a structured way. It will get you thinking the right way.

Expressions of Interest (EOI) now open

uLearnIT is calling for expressions of interest in attending a Developer Certification Preparation course. This course will not be able to be run in every location. We are looking for locations where there is enough interest to make the courses viable. We will need a minimum of eight (8) participants in any location to schedule a course.

If you express interest in the course, there is no commitment on your part to attend and the expression is not an enrolment. When course locations and dates are confirmed, we will open limited enrolment. People who express interest will be given first priority.

If you are interested in this course, please fill out the EOI survey at:

surveymonkey.com/r/7PTZYJS

If you have any questions, please email us at info@ulearnit.com.au or use the contact form on this web site.