Chapter 15. FileMaker XML Reference

About FileMaker and XML

XML (along with its companion technology, XSLT), is the driving technology behind FileMaker’s Custom Web Publishing (CWP). FileMaker Server Advanced can serve out FileMaker data as XML, for use in applications that require XML data. It can also transform the XML data extracted using XSLT stylesheets, to create a variety of output formats, including, of course, an HTML presentation layer.

This section is a reference guide to FileMaker XML syntax. We cover the following areas:

• URL syntax for accessing FileMaker data over the Web
• Syntax of the various FileMaker XML grammars
• FileMaker URL query commands and query string parameters
• Important XML namespaces for use with Custom Web Publishing

We do not cover in detail all of the XSLT extension functions available in Custom Web Publishing.

URL Syntax for Web Access to FileMaker Data

FileMaker can provide data in XML format in two ways: via the Export As XML feature in the regular FileMaker client, and via URL-based access requests sent directly to databases hosted via FileMaker Server Advanced.

A URL designed to extract data from FileMaker Server Advanced has two components: a resource name, and a query string. This section demonstrates the correct syntax for resource names within a URL. The query string is made up of potentially many commands and parameters: later sections of this chapter discuss those in more detail.

For more information on the structure of query requests, see “Query Parameters for XML/XSLT URL Requests,” later in this chapter.

URL Syntax for XML Access

In order to extract data from FileMaker Server Advanced in XML format, a URL of the following form is used:

<protocol>://<host>[:<port>]/fmi/xml/<grammar>.xml?<query string>

• <protocol> is either http (for regular HTTP access) or https (for secure HTTP access).
• <host> is the hostname or the IP address of the web server that’s been configured with FileMaker Server Advanced. (Note that if the web server is on a machine other than the FileMaker Server, it’s the address of the web server that must be used here, not that of the FileMaker Server machine.)
• <port> need only be specified if the web server has been configured to run on a port other than the default for the specified protocol (80 for HTTP, 443 for HTTPS).
• <grammar> is the name of one of the four valid FileMaker XML grammars, discussed in the next section.
• <query string> is a query string composed of some number of query parameters in combination with a query command. Specifics are discussed in upcoming sections.

Example:

http://my.filemakerserver.net:8080/fmi/xml/fmresultset.xml?-dbnames

This query will access a server running on port 8080 on the machine my.filemakerserver.net, and will request a list of all databases available for XML access on that server, with the results returned in the fmresultset grammar.

URL Syntax for Access to Container Objects

FileMaker Server Advanced has a special URL syntax for accessing data in container fields. Such a request will cause the container data to be returned directly (much like clicking on a PDF link in a web page). The exact mechanism depends on whether the container data is stored directly in the database, or stored by reference. In order to extract container data stored directly in a FileMaker database, a URL of the following form is used:

<protocol>://<host>[:<port>]/fmi/xml/cnt/data.<extension>?<query string>

• <protocol>, <host>, <port>, and <query string> are as described in the previous section.
• <extension> is the file type extension for the container data being fetched (.jpg, .txt, and the like). This extension allows the web server to set the MIME type of the data correctly.

The query string must contain a –field query parameter with a fully qualified field name, meaning it must contain a repetition index number reference even if the field is not a repeating field.

Example:

http://my.filemakerserver.net:8080/fmi/xml/cnt/data.tiffgif?-db=Customers&-lay=web_search&-field=photo[1]&-recid=303

This URL will extract container data from a specific field (called photo) from the record with recid=303. Even though photo is not a repeating field, the syntax photo[1] is still necessary. The web server will return this container data as GIF data, assuming the .gif suffix is correctly mapped to the TIFF MIME type on the server.

For information on how to manage container data when the container data is stored only by reference, please see the FileMaker Server Custom Web Publishing Documentation.

URL Syntax for XSLT Access

When extracting XML data from FileMaker Server Advanced, it’s also possible to apply an XSLT stylesheet in order to transform the XML into something else, such as an HTML page. The syntax for XSLT access is as follows:

<protocol>://<host>[:<port>]/fmi/xsl/<path>/<stylesheet>.xsl?<query string>

• <protocol>, <host>, <port>, and <query string> are as described in the previous sections.
• The <path> element is optional. Without it, the Web Publishing engine will look for the specified stylesheet within the xslt-template-files directory on the web server. If you wish to create additional directory structures within the xslt-template-files folder, the relative path to the stylesheet must be specified here.
• <stylesheet> is the name of the stylesheet that will be applied to the XML data.

Example:

http://my.filemakerserver.net/fmi/xsl/customer-files/customer_list.xsl?-db=Customer&-lay=list&-max=50&-findall

FileMaker XML Grammars

FileMaker can publish data in any of four XML “grammars.” Note that the grammar names are case sensitive.

• FMPXMLRESULT— This grammar is available either via Custom Web Publishing or via Export As XML. It’s a complete data export grammar, but can be a bit difficult to parse or read.
• FMPDSORESULT— Also a complete data export grammar, available via either CWP or export, but this grammar has been deprecated and we recommend that you do not use it.
• fmresultset— This grammar was introduced with FileMaker Server 7 Advanced and is in some sense the “best” data export grammar, being rather easier to parse and read than FMPXMLRESULT. We recommend you use it where possible. It is available only via CWP using FileMaker Server Advanced, not via Export As XML.
• FMPXMLLAYOUT— A specialized grammar used for extracting information about a FileMaker layout. Only available via CWP.

Following is a sample of each grammar.

FMPXMLRESULT

FMPDSORESULT

fmresultset

FMPXMLLAYOUT

Query Parameters for XML/XSLT URL Requests

The FileMaker Web Publishing Engine delivers XML data in response to specially formatted URLs. The specific details of the request are contained in the query string, which is a specific portion of the URL. For example, the query string is highlighted in the following URL:

http://my.filemakerserver.net/fmi/xsl/customer-files/customer_list.xsl?-db=Customer&-lay=list&-max=50&-findall

The query string consists of a series of name-value pairs, of the form name=value, separated by ampersands, and following a question mark within the URL.

Generally, a query string intended for the Web Publishing Engine consists of a single query command, representing the type of request being made, supported by additional query parameters that add specificity to the request. In the preceding example, the request is –findall (find all records). Additional query parameters specify the database, the layout, and the maximum number of records to be returned.

Please note the following important points about URL queries.

• Each URL query string must contain one and only one query command (though it may contain many additional query parameters).
• Query commands and query parameters begin with a hyphen (-). Omitting the hyphen will cause an error.
• A query command is expressed as a plain name, not as a name-value pair. Any supplied value will be ignored. (So you can say ...&-findall=somevalue, but the =somevalue will be ignored.)
• The names of FileMaker fields, when included in the URL for purposes of searching, or creating or editing records, do not require a hyphen.
• Most query commands have a minimum set of query parameters that must also be provided in the URL. These are noted in the tables below.

Query Commands

This section lists the possible query commands. If the command requires certain specific additional parameters, those are listed.

Query Parameters

FileMaker XML and XSLT Namespaces

FileMaker’s XML and XSLT publishing technologies use a number of XML namespaces. Each of the four XML grammars has its own namespace. In addition, a number of the XSLT features of Custom Web Publishing have their own namespaces as well. You generally only need to concern yourself with namespaces if you are writing XSLT stylesheets that transform FileMaker XML data.

Table 15.1 lists each namespace, along with its significance, and the conventional namespace prefix used to abbreviate it. The prefix is “conventional” in the sense that, in creating a stylesheet, you may choose any prefix you want for a namespace, but the ones listed below are those used by FileMaker, Inc., in the official documentation.

Table 15.1. Namespace Usage and Prefixes

(*) Since the FMPDSORESULT grammar is deprecated, FileMaker makes no recommendation for a default prefix.