FileMaker Cloud 2.18 OData Guide
About using OData with FileMaker databases
Overview
Open Data Protocol (OData) is an industry-standard API implementation that provides a standard method for querying and updating data, allowing REST API clients to access FileMaker® data hosted by FileMaker Cloud®. OData conforms to Representational State Transfer (REST) architecture and is therefore a REST API. OData is similar to Open Database Connectivity (ODBC) and Java Database Connectivity (JDBC), as it gives third-party applications such as Excel a standard method for accessing FileMaker data. See OData 4.0 Protocol.
In addition, OData returns data in JavaScript Object Notation (JSON) and Atom Syndication Format (Atom). JSON is a text format that is commonly used with REST APIs because it is compact and human readable. Atom is an XML format used for creating and updating web resources, and is supported for applications that use XML-structured data instead of JSON.
This guide assumes you're experienced with:
- using FileMaker Pro Advanced to create databases. You should understand the basics of FileMaker Pro Advanced database design and the concepts of fields, tables, relationships, and containers. See FileMaker Pro Advanced Help.
- using FileMaker Cloud to host databases. You should understand how to set up FileMaker Cloud, enable access to hosted databases, and monitor hosted databases using FileMaker Cloud Admin Console. See FileMaker Cloud documentation in the Product Documentation Center.
- using REST APIs in server-side applications or web services that call POST, GET, PATCH, and DELETE methods.
General steps for using OData with FileMaker databases
- Prepare your FileMaker database for OData access using FileMaker Pro Advanced. See Enable OData access.
- Write code that calls OData methods to find records, modify records, run FileMaker scripts, and modify the schema of a hosted database. See Write OData calls.
- Host your FileMaker database using FileMaker Cloud with OData access enabled. See Host databases for OData access.
- Test to ensure that OData access is working correctly. See Test OData access.
- Monitor your hosted database using FileMaker Cloud Admin Console. See Monitor OData access.
How OData calls are processed
REST API client
1
6
Web server
2
5
OData Listener
3
4
Database Server
- A REST API client sends an OData call (HTTPS request) to the web server over the HTTPS port (port 443).
- The web server routes the request through the FileMaker Web Server Module to the FileMaker OData Listener.
- The OData Listener converts the HTTPS request (URL with JSON or Atom data) into a format that the Database Server component can understand, and requests data from the database hosted by the Database Server.
- The Database Server sends the requested FileMaker data back to the OData Listener.
- The OData Listener converts FileMaker data into an HTTPS response (URL with JSON or Atom data) to the call, passing the data back to the web server.
- The web server sends the HTTPS response to the requesting REST API client.
API solution comparison
The FileMaker Platform provides two REST APIs for accessing data in hosted FileMaker databases. Determine which solution makes sense for your business goals and environment.
| Solution | Use when | Advantages |
|---|---|---|
| OData standard |
|
|
| FileMaker Data API |
|
|
OData and FileMaker terminology
This guide uses FileMaker terminology where possible. For clarity, the OData term is sometimes used along with the FileMaker term. The following table shows equivalent terms and definitions.
For information on FileMaker terminology, see the Product Documentation Center.
| OData term | FileMaker term |
|---|---|
| entity | record |
| entity set | table |
| entity container | group of fields that is not necessarily a record (such as a database name and URL) |
| collection of entity containers | list of a group of fields (for example, a list of database names) |
| property | field |
| path segment | value between two slash characters (in a URL) |
| raw value | a binary value that is a string of bytes rather than a human-readable structured JSON or Atom value |
Prepare databases for OData access
Enable OData access
To allow OData access to FileMaker data, you must enable the fmodata extended privilege in FileMaker Pro Advanced. If you don't enable the fmodata extended privilege, OData applications won't be able to use OData calls to access the database even if the database is hosted.
Note:For security reasons, enable the fmodata extended privilege only in the privilege sets for accounts that you want to allow access via OData.
See "Editing extended privileges for a privilege set" in FileMaker Pro Advanced Help.
OData standard conformance and feature support
OData supported features
OData uses conventions that work with existing standards (REST, JSON, XML, Atom) to provide representation for common functionality. The FileMaker Platform supports OData at the intermediate conformance level, with some exceptions. See the OData 4.0 Protocol specification and reference guide.
You can use the OData API to:
- retrieve information about FileMaker Cloud; for example, hosted database names and table names, and metadata for a database. See Database structure and metadata.
- create, edit, or delete a record. See Modifying data.
- find a record, or find all records. See Request data.
- specify criteria to find a set of records. See Query options.
- run FileMaker scripts. See Run scripts.
- upload container data. See Work with container data.
OData unsupported features
These OData features from the intermediate conformance level are not supported:
$searchquery option$expand(supported only as part of a$crossjoinoperation)lambdaoperatorsanyandall$filteron expanded entitiesbuild-in canonical functions and operators:
- indexof()
- fractionalseconds()
- isof()
- geo.distance()
- geo.length()
- geo.intersects()
In addition, the following actions are not supported:
- access to data in external ODBC data sources
- use of FileMaker plug-ins
- script trigger activation through user interaction; OData activates script triggers only by running a FileMaker script
- access to the server machine's file system; for example, OData does not support the Get (TemporaryPath) function
OData reference information
Several API references provide specifications for OData:
URL and data format notes
- The maximum URL length is be influenced by differences in operating systems, web servers, and web browsers. For optimal cross-platform use, limit the URL length to 2,000 characters.
- Strings in URLs must use URL encoding, also known as percent encoding, which is normal for HTTP requests.
- String data values specified in parameters in the body of the request must use UTF-8 encoding.
FileMaker scripts and OData
A FileMaker script is a named set of script steps that automate frequently performed tasks, and that can combine several tasks. When used with OData, FileMaker scripts allow web services to perform more tasks or a series of tasks. See Run scripts.
Notes
- Use accounts and privileges to restrict the set of scripts that a web service can run. Verify that the scripts contain only web-compatible script steps, and provide access only to scripts that should be used from a web service.
- Consider the effects of scripts that run a combination of steps controlled by access privileges. For example, if a script includes a step to delete records, and the web service does not log in with an account that allows record deletion, the script will not perform the Delete Records script step. However, the script might continue to run, which could lead to unexpected results.
- In the Script Workspace, grant the Full Access privilege set to a script to allow the script to perform tasks that you would not grant to individuals. For example, you can prevent users from deleting records with their accounts and privileges, but allow them to run a script that would delete certain records under conditions defined in the script.
- Any script that modifies data should include the Commit Record/Request script step, because data changes aren't accessible until the data is saved to the server. This includes script steps like Cut, Copy, and Paste. Convert single actions into scripts to include the Commit Record/Request script step. When designing scripts that are run from a web service, include the Commit Record/Request script step at the end of a script to make sure all changes are saved.
- Open each script that web users might run, and verify that the script runs properly when the database is hosted for OData access. Check that the script uses only script steps that are supported by OData, as described above.
Write OData API calls
OData call components
OData calls consist of the following components.
| Component | Description |
|---|---|
| HTTP method | OData uses the following HTTP methods:
|
| HTTP headers | OData uses the following headers:
|
| URL | https://host/fmi/odata/version/database-name host – FileMaker Cloud host name Example: |
| Parameter data in JSON and Atom Example | For POST and PATCH methods only. |
Creating an authenticated connection to the FileMaker host
OData requires authentication via a FileMaker ID account.
To define a connection to the FileMaker host:
- Generate a FileMaker ID token for external authentication. See FileMaker Customer Console Help.
- Include the FileMaker ID token from step 1 in the Authorization header for all OData calls.
For example, use the following URL and header:
- URL:
https://host/fmi/odata/v4/database-name/$metadataHost - FileMaker Cloud host name
database-name - name of the FileMaker database - Header:
Authorization FMID FileMaker_ID_Token
- URL:
Database structure and metadata
Information about hosted databases and their structure is available by performing HTTP GET methods.
Get database names
To return a list of database names, use the GET method without specifying a database name in the URL.
| Component | Description |
|---|---|
| HTTP method | GET |
| URL | https://host/fmi/odata/version host – FileMaker Cloud host name Example: |
FileMaker information
- OData returns a list of database names and their corresponding endpoint URLs.
Get list of tables
To retrieve a list of tables in a database, use the HTTP GET method with the database name appended in the URL.
| Component | Description |
|---|---|
| HTTP method | GET |
| URL | https://host/fmi/odata/version/database-name host – FileMaker Cloud host name Example: |
Get metadata
To request table metadata information, use the HTTP GET method.
Use the $metadata keyword with the database service root to request a complete metadata listing for the database.
| Component | Description |
|---|---|
| HTTP method | GET |
| URL | https://host/fmi/odata/version/database-name/$metadata host – FileMaker Cloud host name Example: |
FileMaker information
To provide information about the FileMaker tables in the database, annotations (information not defined in the OData standard) are added to the metadata results, such as the FileMaker product version number.
The annotations below have a Boolean value of true if they are present. Otherwise, the value is false.
- AutoGenerated: whether the field value is automatically generated by FileMaker Pro Advanced
- Index: whether the field values are indexed
- VersionID: whether the field is a timestamp field and a new timestamp value is generated when the record is modified
- Global: whether the field contains a global value
- Calculation: whether the field is a calculation type
- Summary: whether the field is a Summary type
Other annotations:
- MaxRepetitions: an integer value indicating maximum repetitions defined for a repeating field. If this annotation is not present, the field is not a repeating field.
- ExternalSecurePath: a string indicating the relative path specified for secure storage of a container field.
- BestRowID: always contains ROWID, a system field that is explicitly included in a result set by specifying
$select=ROWID. The value in the result set is the same as the Get (RecordID) function for a record. - RowVersion: always contains ROWMODID, a system field that is explicitly included in a result set by specifying
$select=ROWMODID. The value in the result set is the same as the Get (RecordModificationCount) function for a record.
Important: OData requires that each table define a primary key. OData uses fields that are not empty and that require a unique value as a primary key. Therefore, if you don’t have such fields defined for your tables, the ROWID system field is used as the primary key. The ROWID system field contains the same value as the Get (RecordID) function for the record.
Modifying data
OData supports Create, Update, and Delete operations for records according to the access privileges assigned to an account.
Create a record
To create a record for a table, use the POST method. The POST body must contain a single record's data in JSON format.
| Component | Description |
|---|---|
| HTTP method | POST |
| URL | https://host/fmi/odata/version/database-name/table-name host – FileMaker Cloud host name Example: |
| Parameters | JSON example: {Atom example: |
FileMaker information
- Values for individual repetitions in a repeating field are provided by specifying the repetition number in brackets (for example,
Name[4]). - If you create a record with empty data objects in JSON format, at least one field must allow null values.
- FileMaker global fields are read-only and cannot be updated with OData.
Delete a record
To delete a record, use the HTTP DELETE method, specifying the table name and the primary key value of the record in the URL.
| Component | Description |
|---|---|
| HTTP method | DELETE |
| URL | https://host/fmi/odata/version/database-name/table-name (primary-key-value) host – FileMaker Cloud host name Example: |
FileMaker information
- You can delete multiple records by specifying
$filtercriteria.
Update a record
To update a record, use an HTTP PATCH method with the record that you want to update in the URL.
| Component | Description |
|---|---|
| HTTP method | PATCH |
| URL | https://host/fmi/odata/version/database-name/table-name (primary-key-value) host – FileMaker Cloud host name Example: |
| Parameters | JSON example: { |
FileMaker information
- Container values are updated either by providing a Base64 encoded value as described in Update a record with an image or PDF container field, or by providing the binary data described in Update a record with an image or PDF container field with binary data.
- Values for individual repetitions of repeating fields are provided by specifying the repetition index in brackets (for example,
Name[4]). Specifying a repetition of a container field is not supported when updating a record. - You can update multiple records by specifying
$filtercriteria.
Work with container data
You can send a HTTP POST or PATCH method to insert pictures or PDF files into container fields. Data in container fields are embedded in the field, stored by file reference, or stored externally.
Create a record with an image or PDF container field
To create a record for a table with one or more container fields, set the field with Base64 encoded data. Only GIF, PNG, JPEG, TIFF, and PDF file types are supported. The POST body must contain a single valid record representation.
| Component | Description |
|---|---|
| HTTP method | POST |
| URL | https://host/fmi/odata/version/database-name/table-name host – FileMaker Cloud host name Example: |
| Parameters | JSON example: { |
FileMaker information
- The media type of a Base64 encoded container value is determined by comparing the first bytes of the data to expected values for the supported media types.
Update a record with an image or PDF container field with binary data
The request in this table updates the value in a photo field of a Contacts record using the PATCH method with binary GIF bytes (unstructured) in the body of the request. The content type header must specify the type of data contained in the body (image/gif, image/png, image/jpeg, image/tiff, or application/pdf).
| Component | Description |
|---|---|
| HTTP method | PATCH |
| URL | https://host/fmi/odata/version/database-name/table-name (primary-key-value)/field-name host – FileMaker Cloud host name Example: |
| Parameters | "474946383961090009008001007F7F7FFFFFFF21F90401000001002C00000000090009 |
Update a record with an image or PDF container field
To update the value of a container field for a record, use the HTTP PATCH method with Base64 encoded value.
| Component | Description |
|---|---|
| HTTP method | PATCH |
| URL | https://host/fmi/odata/version/database-name/table-name (primary-key-value) host – FileMaker Cloud host name Example: |
| Parameters | JSON example: { |
Request data
Request records from a table
To return a collection of records from the FileMaker database, use the HTTP GET method with the table name included in the URL.
| Component | Description |
|---|---|
| HTTP method | GET |
| URL | https://host/fmi/odata/version/database-name/table-name host – FileMaker Cloud host name Example: |
FileMaker information
- Container fields are not included in the response result when you get all records or a single record. See Request an individual field value for information about requesting container field values.
Request an individual record
To request an individual record in a database table, specify the database name and table name, and the primary key value for the record.
| Component | Description |
|---|---|
| HTTP method | GET |
| URL | https://host/fmi/odata/version/database-name/table-name (primary-key-value) host – FileMaker Cloud host name Example: |
FileMaker information
- The primary key value specified in the URL is the field designated as the primary key, or the ROWID system field if no primary key has been designated. See Get metadata. For repeating fields, the value of the first repetition is included. To get individual repetitions, see Request an individual field value.
Request an individual field value
To request an individual field value, specify the table name, primary key value for the record, and the field name.
| Component | Description |
|---|---|
| HTTP method | GET |
| URL | https://host/fmi/odata/version/database-name/table-name (primary-key-value)/field-name host – FileMaker Cloud host name Example: |
FileMaker information
- In a URL, when requesting an individual repetition, using brackets ([ ]) to specify the repetition index is not supported.
- If the repetition field is a container field, only the first repetition is returned. Otherwise, all repetitions are returned.
Request the binary value for an individual field
To request an individual field stored as a binary value, use the query option $value.
The binary value default format for the FileMaker field is text/plain. For container fields, the default format depends on the type of container field and includes image/gif, image/png, image/jpeg, image/tiff, application/pdf, or application/octet-stream.
| Component | Description |
|---|---|
| HTTP method | GET |
| URL | https://host/fmi/odata/version/database-name/table-name (primary-key-value)/field-name/$value host – FileMaker Cloud host name Example: The request above returns the binary value of the Name field for the Contacts record. |
FileMaker information
- When requesting the binary (raw) value of a repetition field, only the binary (raw) value of the first repetition is returned.
Navigate related tables
You can navigate relationships between FileMaker tables without specifying the match fields for each relationship. All operations and results are associated with the last table in the URL.
| Component | Description |
|---|---|
| HTTP method | GET |
| URL | https://host/fmi/odata/version/database-name/table-name (primary-key-value)/related-table host – FileMaker Cloud host name Example: The request above returns all products purchased by a customer with the given ID. |
FileMaker information
- When using the
$filterquery option, field names are disambiguated by prepending the table name to the field name in the expression (for example,$filter=Purchase/ID eq 7).
Request a cross join of unrelated tables
To request a cross join of unrelated tables, use the $crossjoin keyword and list the tables that you want to join. When using the $filter query option, specify each field used for joining the two tables.
Use the $expand query option and the $select query option to ensure that data fields are returned rather than the default behavior, which returns a list of record IDs. See "Addressing the cross join of entity sets" in OData 4.0 URL Conventions.
Note: A cross join is the only context where the $expand keyword is supported.
| Component | Description |
|---|---|
| HTTP method | GET |
| URL | https://host/fmi/odata/version/database-name/$crossjoin(table 1, table 2)?$filter= host – FileMaker Cloud host name Example: |
Query options
OData supports various query options for querying data.
Query option $filter
Use the $filter query option to filter the records. The expression specified with $filter is evaluated for each record in the collection, and only items where the expression evaluates to true are included in the response.
OData supports a set of built-in operators and functions that are used within $filter operations. For more information about available operators and built-in functions, see OData 4.0 Protocol.
| Component | Description |
|---|---|
| HTTP method | GET |
| URL | https://host/fmi/odata/version/database-name/table-name?$filter=(expression) host – FileMaker Cloud host name Example: The request above uses the GET method and the |
FileMaker information
The following built-in functions are not supported:
- indexof()
- isof()
- geo.distance()
- geo.length()
- geo.intersects()
- fractionalseconds()
- Date, time, and timestamp formats conform to ISO 8601. Time zone offsets are relative to the time zone of the server.
- Enclose field names that include special characters, such as spaces or underscores, in double-quotation marks.
Query option $orderby
Use the $orderby query option to request records in either ascending or descending order. If you don't specify an order, the default order is ascending.
| Component | Description |
|---|---|
| HTTP method | GET |
| URL | https://host/fmi/odata/version/database-name/table-name?$orderby=field-name {asc/desc} host – FileMaker Cloud host name Example: The request above sorts Contacts records in descending order by the Company field. |
FileMaker information
- Enclose field names that include special characters, such as spaces or underscores, in double-quotation marks.
- The
$orderbyquery option doesn't support OData built-in functions.
Query option $top and $skip
Use the $top and $skip query options to page through a larger result set. You can use these query options alone or together, depending on which records you want in your response.
| Component | Description |
|---|---|
| HTTP method | GET |
| URL | https://host/fmi/odata/version/database-name/table-name{?$top/?$skip}=number host – FileMaker Cloud host name Query options {?$top/?$skip} - the Example:
|
Query option $count
Use the $count query option (value set to true) to request a count of matching records returned along with the records in the response. The $count query option ignores any $top or $skip query options, and returns the total count of results across all records including the results matching the $filter criteria (if specified).
| Component | Description |
|---|---|
| HTTP method | GET |
| URL | https://host/fmi/odata/version/database-name/table-name?$count=true host – FileMaker Cloud host name Example: |
Query option $select
Use the $select query option to request a limited set of fields for each table. The default is to return all fields except container fields.
| Component | Description |
|---|---|
| HTTP method | GET |
| URL | https://host/fmi/odata/version/database-name/table-name?$select=field 1, field 2 host – FileMaker Cloud host name Example: The request above returns the Company and Website data for all records in the Contacts table. |
FileMaker information
- The ROWID and ROWMODID system field is included in the result set by specifying them with the
$selectquery option. For example:$select=ROWID, ROWMODID. - ROWID is equivalent to the value returned by the Get (RecordID) function, and ROWMODID is equivalent to the value returned by the Get (RecordModificationCount) function.
Modify schema
OData supports Create and Delete operations for creating and deleting tables and indexes, according to the access privileges defined for an account.
Create a table
To create a new table, use the HTTP POST method. The POST body must contain a single valid table representation, which includes an identifier that is the table name.
| Component | Description |
|---|---|
| HTTP method | POST |
| URL | https://host/fmi/odata/version/database-name/FileMaker_Tables host – FileMaker Cloud host name Example: |
| Parameters | JSON example: {
"tableName": "Company",
"fields": [
{
"name": "Company ID",
"type": "int",
"primary": true
},
{
"name": "User ID",
"type": "varchar(20)",
"unique": true,
"default": "CURRENT_USER"
},
{
"name": "Company Name",
"type": "varchar(100)",
"nullable": false
},
{
"name": "Notes",
"type": "varchar(2000)",
"global": true
},
{
"name": "Signed Contract",
"type": "blob",
"externalSecurePath": "Files/ContactMgmt/"
}
]
} Atom example: <TableDefinition tableName="Company">
<FieldDefinition name="Company ID" type="int" primary="true"/>
<FieldDefinition name="User ID"
type="varchar(20)"unique="true" default="CURRENT_USER"/>
<FieldDefinition name="Company Name" type="varchar(100)" nullable="false"/>
<FieldDefinition name="Notes" type="varchar(2000) global="true"/>
</TableDefinition> |
FileMaker information
- FileMaker_Tables is a system table used for creating, modifying, and deleting tables. The
typeparameter is one of the following types: NUMERIC, DECIMAL, INT, DATE, TIME, TIMESTAMP, VARCHAR, CHARACTER VARYING, BLOB, VARBINARY, LONGVARBINARY, or BINARY VARYING. - Repetitions are specified in brackets after the type (for example,
"INT[4]"). You can specify the maximum length of a text field in parentheses (for example,"VARCHAR(200)"). Optional parameters are used with the field name and field type:
"primary": true or false (whether the field is a primary key; default is false)"unique": true or false (whether the field must have a unique value; default is false)"nullable": true or false (whether the field must have a value; default is true)"global": true or false (whether the field is global; default is false)"default": a string containing a keyword that's appropriate for the data type; valid keywords are USER, USERNAME, CURRENT_USER, CURRENT_DATE, CURDATE, CURRENT_TIME, CURTIME, CURRENT_TIMESTAMP, and CURTIMESTAMP"externalSecurePath"(container field only): a string containing a relative path for secure files in "externalSecurePath". Exclude the "[database location]/" portion of the base directory. Be sure to set this for each FileMaker database in FileMaker Pro Advanced. See FileMaker Pro Advanced Help.
Add fields into a table
To create a new field in an existing table, send a PATCH request to the FileMaker_Tables system table, followed by the table name in the URL. The PATCH body must contain an array of fields to add to the table.
If the request fails because of an error while adding a field, other fields can still be added to the table.
| Component | Description |
|---|---|
| HTTP method | PATCH |
| URL | https://host/fmi/odata/version/database-name/FileMaker_Tables/table-name host – FileMaker Cloud host name Example: The request above creates a field named Phone in the Company table. |
| Parameters | JSON example: { "fields": [ { "name": "Phone", "type": "varchar(25)" } ] } Atom example: <TableDefinition tableName="Company">
<FieldDefinition name="Phone" type="varchar(25)"/>
</TableDefinition>
|
FileMaker information
- FileMaker_Tables is a system table used for creating, modifying, and deleting tables. See Create a table for valid options.
Delete a table
To delete a table and all its records, use the HTTP DELETE method, and use the table name in the URL.
| Component | Description |
|---|---|
| HTTP method | DELETE |
| URL | https://host/fmi/odata/version/database-name/FileMaker_Tables/table-name host – FileMaker Cloud host name Example: |
FileMaker information
- FileMaker_Tables is a system table used for creating, modifying, and deleting tables.
- This operation deletes a table and all data in it without requiring confirmation. To prevent data loss, create an account with access privileges for deleting tables, and use that account exclusively for this operation.
Delete a field from a table
To delete a field from a table, use the HTTP DELETE method with the field name appended to the table name in the URL.
| Component | Description |
|---|---|
| HTTP method | DELETE |
| URL | https://host/fmi/odata/version/database-name/FileMaker_Tables/table-name/field-name host – FileMaker Cloud host name Example: |
Create a field index
To create a new index, send a POST request to the table name after the FileMaker_Indexes system table. The POST body must contain a single valid index representation, which is an identifier that is the field name.
| Component | Description |
|---|---|
| HTTP method | POST |
| URL | https://host/fmi/odata/version/database-name/FileMaker_Indexes/table-name host – FileMaker Cloud host name Example: |
| Parameters | JSON example: { Atom example: <IndexDefinition indexName="State"/> |
FileMaker information
- FileMaker_Indexes is a system table used for creating and deleting indexes.
Delete an index
To delete an index, send an HTTP DELETE request to the FileMaker_Indexes system table, followed by the table name and field name in the URL.
| Component | Description |
|---|---|
| HTTP method | DELETE |
| URL | https://host/fmi/odata/version/database-name/FileMaker_Indexes/table-name/field-name host – FileMaker Cloud host name Example: |
FileMaker information
- FileMaker_Indexes is a system table used for creating and deleting indexes in fields.
- To delete an index, the URL must specify the table name first, followed by the field name.
Run scripts
To run a script, send a POST request to the Script system table, followed by the name of the script in the URL. The POST body must be completely empty if the script does not take a parameter, or it must contain a single field named scriptParameterValue if a parameter is passed to the script. The scriptParameterValue accepts string, number, and JSON object type values.
OData doesn't support script names with special characters (for example, @, &, /) or script names beginning with a number. If the script contains the Exit Script script step, the text result of Exit Script is returned in a field named resultParameter in the results.
The HelloScript script appends the parameter value to the string "Hello" and returns the result. OData returns the result in the response body with a Content-Type of "application/json":
{
"scriptResult":
{
"code": 0,
"resultParameter": "Hello World"
}
}
Note: OData only supports scripts that run without user interaction.
Run a script
To run a script, use the HTTP POST method.
| Component | Description |
|---|---|
| HTTP method | POST |
| URL | https://host/fmi/odata/version/database-name/Script.script-name host – FileMaker Cloud host name Example: World. |
| Parameters | JSON example: |
FileMaker information
- To conform with the OData concept of an action, all scripts are members of a system table named Script.
Host, test, and monitor OData
Host databases for OData access
- Complete the steps in Enable OData access.
- Check that OData access to FileMaker databases is enabled and properly configured in FileMaker Cloud Admin Console. See FileMaker Cloud documentation in the Product Documentation Center.
- Verify that the web server and the OData Listener are running.
-
Use encryption for communication.
OData requires that you use an HTTPS connection. HTTPS connections use Secure Sockets Layer (SSL) encryption for communication.
The programming language or technology used to call the OData API must support Transport Layer Security (TLS) v1.2 to communicate with the web server.
Test OData access
Before putting your OData API in production, verify that it functions as you expect.
- Test features like finding, adding, and deleting records with different accounts and privilege sets.
- Verify that privilege sets perform as expected by testing them with different accounts. Make sure unauthorized users can't access or modify your data.
- Test that your solution behaves the same when run in different operating systems.
Monitor OData access
The server administrator uses FileMaker Customer Console to start or stop the OData Listener, track OData call use, and download the OData log file.
| To | Use |
|---|---|
| Start or stop the OData Listener | The FileMaker Customer Console Connectors > OData tab. See FileMaker Cloud Help in the Product Documentation Center. |
| Track OData API call use | The FileMaker Customer Console Connectors > OData tab. This tab displays the OData annual limit set by your FileMaker Cloud subscription, the amount of data that has been transmitted since the prior annual reset date, and the annual reset date for your subscription. If you are approaching the annual limit, you can increase the limit by using the FileMaker Customer Console Subscription tab. See FileMaker Customer Console Help in the Product Documentation Center. |
| View the OData API log | While OData clients are connected to a database, statistical data about the clients is logged to the fmodata.log file. See FileMaker Cloud Help in the Product Documentation Center. |