FileMaker 18 Admin API Guide

This guide provides information about using Claris^™ FileMaker^® Admin API version 2 (v2) to perform administrative tasks on Claris FileMaker Cloud^® products and Claris FileMaker Server^™. (To learn about FileMaker Admin API version 1 (v1), see FileMaker Admin API Reference, installed with supported products.)

This guide assumes you are experienced with:

• using Claris FileMaker Pro^™ Advanced to upload databases. See FileMaker Pro Advanced Help.
• using FileMaker Server or a FileMaker Cloud product to host and manage databases. See FileMaker Server Help, or FileMaker Cloud product documentation in the Product Documentation Center.
• using REST APIs in server-side applications or web services that call POST, GET, PATCH, PUT, and DELETE methods with data in JSON format. You can use any programming languages or tools you choose.

Notes

• FileMaker Cloud is a service that provides access in the cloud to custom apps that use FileMaker Pro Advanced, Claris FileMaker Go^®, and Claris FileMaker WebDirect^™. FileMaker Cloud uses the FileMaker ID integrated sign-on system to authenticate users and is offered directly from Claris International Inc.
• FileMaker Cloud for AWS is a service that provides access in the cloud to custom apps that use FileMaker Pro Advanced, FileMaker Go, and FileMaker WebDirect. FileMaker Cloud for AWS runs on the Amazon Web Services (AWS) Cloud and is offered through AWS Marketplace.
• FileMaker Cloud products refers to both FileMaker Cloud and FileMaker Cloud for AWS.
• This guide uses Admin Console to refer to Admin Console for FileMaker Server, FileMaker Cloud for AWS, and FileMaker Cloud, unless describing a particular product. FileMaker Cloud Admin Console refers to Admin Console for both FileMaker Cloud products, unless describing a particular product.
• Custom app, solution, database, and file are all terms for what you create and work with using FileMaker products.
• This guide uses access token to refer to the JSON Web Token required for authentication.

The FileMaker Admin API is an application programming interface (API) that allows web services to perform administrative tasks on FileMaker Cloud products and FileMaker Server through scripting instead of using Admin Console. Because this API conforms to Representational State Transfer (REST) architecture, the FileMaker Admin API is a REST API.

The FileMaker Admin API returns data in JavaScript Object Notation (JSON), a text format that is commonly used with REST APIs because JSON is independent of specific programming language formats.

To use the FileMaker Admin API:

1. Write code that uses FileMaker Admin API calls to perform administrative tasks.
2. Test that FileMaker Admin API access is working correctly.
3. Monitor your results by reviewing the gateway.log file for a FileMaker Cloud product, the event.log file for FileMaker Cloud upload and update API calls, or the fac.log file for FileMaker Server. You can download the gateway.log and event.log files from FileMaker Cloud Admin Console. The fac.log file is located in the following folder: .../FileMaker Server/Admin/FAC/logs.

Notes

• To access data in hosted databases, see FileMaker Data API Guide.

REST API client

1

6

Web server

2

5

FileMaker Admin API Engine

3

4

Database Server

Some of the FileMaker Admin API calls, such as authentication calls, are processed only based on the first two steps below. Other calls, such as calls related to creating schedules or updating the configuration, are processed based on all of the steps below.

1. A REST API client sends a FileMaker Admin API call (an HTTPS request) to the web server.
2. The web server routes the request through the FileMaker Web Server Module to the FileMaker Admin API Engine.
3. The FileMaker Admin API Engine converts the HTTPS request (URL and JSON data) into a format compatible with the FileMaker Database Server.
4. The Database Server sends results of the request back to the FileMaker Admin API Engine.
5. The FileMaker Admin API Engine converts the results into an HTTPS response (URL with JSON data) and passes the response back to the web server.
6. The web server sends the HTTPS response to the requesting REST API client.

FileMaker Admin API Reference is installed with FileMaker Server and FileMaker Cloud products. The reference provides detailed information about all of the calls supported by FileMaker Admin API.

To view the reference for the FileMaker Cloud product, enter the following URL in a browser window:

https://host/fmi/admin/apidoc/

where host is the host name or IP address of the virtual server running the FileMaker Cloud product.

To access the reference for FileMaker Server:

• To view the reference in a browser window on the master machine, enter the following URL:

  https://localhost/fmi/admin/apidoc/

• To view the reference in a browser window on a remote machine, enter the following URL:

  https://host/fmi/admin/apidoc/

• On a Windows server, the reference is in the following folder:

  [drive]:\Program Files\FileMaker\FileMaker Server\Documentation\Admin API Documentation

  where [drive] is the drive on which your FileMaker Server deployment resides.

  If you install using a non-default location on Windows, your installation location replaces the beginning of the default installation path:

  [drive]:installation_location\FileMaker\FileMaker Server\Documentation\Admin API Documentation

• On a macOS server, the reference files are in the following folder:

  /Library/FileMaker Server/Documentation/Admin API Documentation

Notes

• The FileMaker Cloud API calls for uploading and updating custom apps are not included in the FileMaker Admin API Reference.
• If you use the URL examples in the Admin API Reference, and you open the reference file from your local drive, all examples start with file:///. To use the URLs, replace file:/// with https://YourHostName/fmi/admin/api/v2.

FileMaker Admin API uses an access token to define a connection to the host. The token is valid either until it is invalidated using the Invalidate Access Token call 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.)

Use the authentication call to request an access token from the host using the root administrator account name and password. Include an Authorization header with the value Basic base64-encoded string. The base64-encoded string should be generated based on username:password. You can also use the Basic Authentication scheme for other calls.

If you use the Basic Authentication scheme for the authentication call, the request returns the access token in the response body. If you use the Basic Authentication scheme for other calls, the request returns the access token in the X-FM-Access-Token field in the response header.

For subsequent API calls, use the Bearer Authentication scheme and include an Authorization header with the value Bearer access token.

Notes

• Each time you use the Basic Authentication scheme to get an access token, a new API session is created. To avoid having multiple API sessions, use the same access token with the Bearer Authentication scheme for all API calls.

FileMaker Admin API uses an access token to define a connection to the host. The token is valid either until it is invalidated using the Invalidate Access Token call 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 authenticate accounts for FileMaker Cloud:

1. Generate the FileMaker ID token. See FileMaker Customer Console Help in the Product Documentation Center.

2. Include the FileMaker ID token from step 1 in the authentication call or any other calls to generate an access token.

   For example, use the following URL and header for the authentication call:

   • URL: https://host/fmi/admin/api/v2/user/auth

     where host is the host name or IP address of the virtual server running FileMaker Cloud.

   • Header: Authorization FMID FileMaker_ID_Token

   If you use the authentication call, the access token is returned in the response body. If you use other calls, the token is returned in the X-FM-Access-Token field in the response header.

3. For subsequent API calls, include the following Authorization header for the authentication call:

   Header: Authorization Bearer access token

Notes

• Each time you use the FileMaker ID Authentication scheme to get an access token, a new API session is created. To avoid having multiple API sessions, use the same access token with the Bearer Authentication scheme for all API calls.
• To authenticate accounts for uploading apps to FileMaker Cloud or updating a custom app based on changes in a clone, see Authentication for FileMaker Cloud API calls to upload or update apps.

Use the Authentication API call to return the session key to use with the API calls for uploading apps to FileMaker Cloud or updating an app hosted by FileMaker Cloud.

The following table displays the supported FileMaker Admin API calls for FileMaker Server and FileMaker Cloud products.

• The startupRestorationLogPath parameter for FileMaker Server Admin API specifies the folder path for saving restoration logs. For best results, change the restoration log folder location to a separate disk drive.
• FileMaker Cloud products use the UTC time for the startTimeStamp parameter.
• For filemakerScriptType, you need to provide both the fmScriptAccount and the fmScriptPassword parameters for the script to run.
• In FileMaker Cloud, for filemakerScriptType, use the fmScriptAccount parameter to specify the FileMaker ID token and the fmScriptPassword parameter to specify the FileMaker ID refresh token. If you don’t specify the refresh token, the script can’t run after the FileMaker ID token is expired. To learn how to generate the token, see FileMaker Customer Console Help in the Product Documentation Center.
• When using the FileMaker Admin API to create schedules, the FileMaker Admin API may not validate some values specified in the API request (for example, accounts or passwords).
• The Get Schedule call requires the schedule_id parameter. To find a schedule ID, use the Get Schedules call to list all schedules and their settings.
• If the returned value for the status parameter for the List Databases call is Normal, the database is open.

• API calls related to databases and schedule API calls except for the create and edit/run schedule calls are asynchronous and do not wait for a response from the FileMaker Cloud product or FileMaker Server. You may want to follow an asynchronous call with a GET call to confirm the file status has changed. For example, follow a close database call with a GET databases call to confirm the database is closed. If the status doesn't change immediately, continue checking. The rest of the API calls are synchronous and wait for a response from the FileMaker Cloud product or FileMaker Server.

Note: Before you upload an app, make sure it is encrypted using FileMaker Pro Advanced.

Use the custom app upload API calls in the following order to upload a database and its remote container files to FileMaker Cloud.

1. Check file upload
2. Get database upload info

3. Database upload event

   Use this call with the x-fms-upload-event set to 1 to prepare the host for uploading the files.

4. Upload

   If a file is larger than 500 MB, use the Append call to divide the file into multiple parts and upload each part separately.

5. Database upload event

   Use this call with the x-fms-upload-event set to 2 to complete the uploading process.

   FileMaker Cloud then does the following:

   • verifies that the number of hosted files is fewer than the supported maximum number
   • verifies that the encryption password is valid
   • if needed, saves the encryption password to FileMaker Data Storage
   • synchronizes the database and remote container files with FileMaker Data Storage and moves the uploaded database file to the hosting area
   • verifies that the FileMaker ID account is valid
   • verifies that all the container fields use secure storage, and the file doesn't have any open storage container fields

If you have made schema, layout, or other changes in an app, you can update the hosted app with the changes. To do so, create a clone of the changed file, then use the Update API call to update the original file based on the changes in the modified app. The Update API call moves all record data and user accounts from an app hosted by FileMaker Cloud to a clone, then replaces the original file with the target file. The target file includes all data from the source file and all the schema, layout, and other changes from the clone.

For example, use the Update API call to:

• copy test data or live data into a custom app between different stages of the DTAP (Development, Testing, Acceptance, and Production) cycle
• copy existing data into a new version of a custom app

Advantages of using the Update API call, instead of importing data, include:

• you move all data at once, instead of importing data from each table separately
• the API call maps fields between source and target tables automatically, instead of you mapping them manually for importing
• you can update user accounts, custom value lists, and serial numbers, which you can't do when you import data

Terms used for the updating API topics:

• source file: An FMP12 file that contains the data to use for the target file.
• file to be cloned: A file that includes tables, layouts, scripts, and field definitions to use for the target file. This file can be the same as the source file, or it can be a different file. For example, if you use the Update API call between different stages of the DTAP cycle, the file to be cloned could be in the testing stage while the data to use could be in the production stage.
• clone: A copy of an FMP12 file that contains all the tables, layouts, scripts, and field definitions but none of the data. Use FileMaker Pro Advanced to make a clone, but don't open the clone. Opening a clone modifies it.
• target file: A copy of the clone created by the Update API call, into which data and user accounts from the source file are migrated. The Update API call replaces the original source file with the target file.

• If the account for accessing the source file or the clone doesn't have the Full Access privilege set, create a new extended privilege, called fmmigration, for the account. See FileMaker Pro Advanced Help in the Product Documentation Center.

  The keyword for the extended privilege must start with the fmmigration prefix. The account with this extended privilege doesn't need to have access to any tables, scripts, or layouts. The source and clone extended privilege names must match (but are not case sensitive).

• Both the source file and the clone must be encrypted. The encryption passwords can be different.
• Make sure you know the account name, password, and encryption password (if encrypted) for the source file and the clone.

Create a clone of the file that includes tables, layouts, scripts, and field definitions to use for the target file.

1. In FileMaker Pro Advanced, open the file to be cloned.

2. Choose File menu > Save a Copy As, then choose clone (no records).

   Important:Do not open the clone with FileMaker Pro Advanced.

3. Make sure the source file is closed.

Use the Update API call to apply changes from a clone to an app.

The Update API call uses the following rules to match the data between the source file and the clone.

• Data is moved to the target file only if the names or internal IDs of tables and fields match. The Update API call determines the best match in this order:

  • both the names and the IDs match
  • only the names match
  • only the IDs match

  If no matches are found, the data is not moved to the target file.

• The privilege set for a migrated user account is set to the clone’s privilege set only if the privilege set names or IDs match. The Update API call determines the best match in this order:

  • both the names and the IDs match
  • only the names match
  • only the IDs match

  If no matches are found, a new privilege set, Unmapped Privilege Set, with no privileges assigned is created for the account.

• Custom value lists are moved to the target file only if the names and IDs match, and if the x-fms-ignore-valuelists header isn't used.