Publishing FileMaker Data as XML

Custom Web Publishing falls into two broad categories: CWP with XML and CWP with XSLT. The former technique allows you to publish FileMaker data as raw XML over the Web. The latter technique is XML-based as well, but involves applying additional transformations to the XML to turn it into other data formats such as HTML. Because XML publishing is the basis for both of these flavors of CWP, we begin with a thorough discussion of FileMaker data publishing with XML.

Introduction to XML Publishing

To publish FileMaker data as XML via the Web Publishing Engine, you need several things:

• A web server with the appropriate web server module and the Administration Console installed.
• A running copy of the Web Publishing Engine, with XML publishing enabled. (See the previous section, "Configuring the Web Publishing Engine.")
• A copy of FileMaker Server Advanced thats configured to work with the Web Publishing Engine.
• One or more FileMaker databases that are enabled for XML access via the appropriate extended privilege, and are being served by the server mentioned in the preceding bullet.

Ifand only ifall these pieces are in place, you can draw XML data from a served database by opening a web browser and entering a URL like the following:

http://192.168.100.101/fmi/xml/fmresultset.xml?-db=Animal&-lay=web&-findall

This URL, 192.168.100.101, is the address of the web server that weve configured to work with the Web Publishing Engine. The path to fmresultset.xml indicates that we want the results returned in the fmresultset grammar. URL also instructs the WPE to access a database called Animal, via a layout called Web, and then find all records and return them in the select fmresultset grammar.

Note

Note that its not necessary to include the filename suffix (.fp7) when referencing the database name in the URL.

If you indeed had a database called Animal open under FileMaker Server, and if it had privilege sets with the extended privilege for XML enabled, and it had a layout called Web, the Web Publishing Engine would return an XML document to your browser. If you e using a browser capable of displaying XML (which includes Firefox, Safari, and Internet Explorer), youd see something like the code in Listing 23.1.

Listing 23.1. XML Formatted with the fmresultset Grammar

In general, when you want to access XML data from an appropriately configured FileMaker file, you do so by entering a URL in the following format:

//[:

]/fmi/xml/.xml?[]

Protocol indicates a web protocol, either HTTP or HTTPS.

Server-IP is the IP address of the web server that serves as the point of entry to the Web Publishing Engine. Note that if the Web Publishing Engine is installed on a different machine from the web server, you must specify the IP address of the web server machine hereproviding the address of the Web Publishing Engine does not work.

Port is an optional part of the URL. In general, your web server will be running on the default HTTP port of 80 or the default HTTPS port of 443. If for any reason youve configured your web server to run on a different port than the protocol default, you need to specify that port number here. This port has nothing to do with any of the WPE-specific ports (in the 16000 range) or the FileMaker Server port (5003) that you may have encountered in the Web Publishing Engine documentation; it refers strictly to the port on which your web server accepts incoming requests.

Grammar refers to one of three FileMaker xml grammars: FMPXMLRESULT, FMPXMLLAYOUT, or fmresultset.

Note

Note that only the first one of these is available via XML export: The second two are available only via Custom Web Publishing. The FMPDSORESULT grammar thats available with XML export is not available with Custom Web Publishing.

Query-string refers to a series of one or more specific pieces of information you pass to the Web Publishing Engine to form the substance of your request. Among the pieces of information you would pass in the query string are the name of the database to access, the name of the layout you want to work with, and the name of a database action (such as "find all records", expressed in the sample URL by the -findall command).

In general, then, youll use specially formatted URLs to access FileMaker data as XML via Custom Web Publishing. These URLs can be manually entered in a web browser, or they can be linked from a web page, or they can be used by other processes or applications that want to consume FileMaker data as XML.

Understanding Query Strings

A lot of the action in a Custom Web Publishing URL occurs inside the query stringthat odd-looking set of commands at the end of the URL. Here again is the example URL from the previous section:

http://192.168.100.101/fmi/xml/fmresultset.xml?-db=Animal&-lay=web&-findall

The query string is the portion of the URL that comes after the question mark. A query string consists of multiple name-value pairs, with each name-value pair taking the form name=value. If there are multiple name-value pairs in a URL, additional pairs are separated from the first one by an ampersand character (&).

Note

Query strings are not peculiar to FileMaker or to Custom Web Publishingthey e an HTTP standard for passing information to a server-side program via a URL.

In the sample URL, weve passed three name-value pairs. Table 23.1 shows the names and their corresponding values.

In general, any Custom Web Publishing URL needs to specify at least a database name, a layout name, and a database action to perform. (In fact, the database name and layout name can also be omitted in the case of a few specialized database actions). So, at a minimum, you will usually provide a -db value, a -lay value, and the name of some database action.

A few more notes on query string syntax: The order of the name-value pairs within the query string doesn matter, as long as all the required pairs are present. The initial dash (-) in the various names is significant, however, and can be omitted. Youll notice that the database action consists of a name without a value (which is perfectly legitimate in an HTTP URL query string); database actions always consist of a name with no value attached.

Performing Specific Searches with CWP URLs

The CWP URLs weve looked at so far are simply querying a FileMaker database table, finding all records, and returning the results as raw XML according to the selected XML grammar. But what if you want to query different tables within the chosen database, or select only certain records rather than all records, or apply a sort order to the results? All these things are possible with CWP.

Specifying the Table

One of the reasons its so important to supply a layout name with your CWP URLs (via the -lay parameter) is that the active table is determined by the active layout, via that layouts table context. You may recall that, in the Layout Setup dialog for each layout, theres a choice labeled Show Records From. This enables you to select a table occurrence that will provide the layouts table context. When you specify a layout in a CWP URL, you are implicitly setting the active table as well. All commands in the query string are considered to be applied to whatever table underlies the chosen layout.

Finding Specific Records

The Custom Web Publishing URL can also be used to search for specific records. To do this, use -find as the database action, instead of -findall. You also need to specify one or more search criteria, which are also supplied as name-value pairs.

For example, if you e working with a database of animals, and theres a field called name for the animals name, you can use the following URL to search for any animals named Hector:

http://192.168.100.101/fmi/xml/fmresultset.xml?-db=animal&-lay=web&name=Hector&-find

Note

The database in question has only a single table, also called Animal, and that table is the table context for the web layout.

This code snippet specifies a database action of -find, and adds one more parameter to the query string. We say name=Hector to cause the Web Publishing Engine to search for only records where the name is Hector. If there are any such records, theyll be returned in the chosen XML grammar. If there are no matching records, we get back a response that looks a bit like Listing 23.2.

Listing 23.2. Sample Error Response

You can see that in the case where no records are found, the XML returned by the Web Publishing Engine contains an error code appropriate to the situation. In this case, the code is a standard "no records found" error. (Note that the exact format of the error response varies depending on which XML grammar you specified in the URL.)

Specifying an Exact Match When Searching

In the previous example, the search appeared to be for all animals named Hector. This is not exactly true. The previous URL will have exactly the same effect as entering Find mode in the regular FileMaker client, typing Hector into the name field, and performing the search. FileMaker, when searching text fields, searches on a "starts with" basis, so this search actually finds animals named Hector, Hector II, Hectorax, and so on. To specify that you want an exact match, rather than a "starts with" match, you need a bit more precision. In FileMakers regular Find mode, youd type =Hector in the search field, with the equal sign indicating an exact match. In a CWP URL, youd write:

[View full width]

Another parameter has been added to the query string here. The new parameter specifies what kind of operator we want to apply to one of the search fields. The syntax for this new parameter is

.op=

Here, field-name is the field to which you want to apply the operator, and operator is a short character string indicating one of nine different possible operators. Here, the operator weve chosen is eq for an exact match. Other possible operators are cn for contains, bw for begins with (the default), and ew for ends with. So, if you wanted to find all animals with a name ending in tor, you could use this URL:

http://192.168.100.101/fmi/xml/fmresultset.xml?-db=animal&-lay=web&name=tor&name.op=ew&-find

This query string instructs the Web Publishing Engine to treat the search on the name field as an "ends with" search.

Note

The operators available to you in Custom Web Publishing are similar to, but not identical to, the list you would find in the FileMaker client if you entered Find mode and clicked on the symbol list in the status area. FileMaker Find mode and the Custom Web Publishing find syntax each contain operators that are not available in the other. Table 23.2 lists all the operators available in Custom Web Publishing.

Performing a Numerical Comparison Search

Consider a database that contains some numerical fields. The Animal database used as an example so far contains a field called weight_birth for an animals birth weight. Suppose that you want to find all animals with a birth weight less than 100 pounds. The following URL would do it:

[View full width]

Here, 100 is specified for the weight_birth search field, but we go on to say that the operator for that search field is the less-than operator, symbolized by the code lt.

Searching on Multiple Criteria

Suppose that we want to construct a more narrowly tailored search. You want to find all male animals with a birth weight less than 100. (This is the equivalent of filling in two fields in FileMakers Find mode, instead of just one.) Youd use a URL like the following:

[View full width]

Here weve simply added one more search field: gender=Male. This constitutes a further limit on the search you saw in the previous example. This search finds only records for male animals with birth weight less than 100.

Creating Multiple Find Requests

The preceding example showed how to use multiple criteria to narrow a search. But what if you want to use multiple criteria to broaden a search? Weve searched for animals with birth weight less than 100. What if you also want to find, in the same search, any animals who have a current weight less than 500? (You might recognize this as the equivalent of creating additional Find requests in the regular FileMaker Pro software.)

To explain this kind of search, you need to introduce the concept of a logical operator. In the search demonstrated previously, for a record to be included in the search, all the search criteria in the query string had to be true. That is, an animal would not be included in the search results unless it was both male and had a birth weight less than 100. This kind of search is thus often referred to as an and search or an all-true search.

On the other hand, when you think about also finding animals with current weight less than 500, you have a situation where an animal will be included in the search results if any of the search criteria are true. In other words, a record will be found if the animal had a birth weight of less than 100, or it has a current weight of less than 500. This type of search is thus often called an or or an any-true search.

By default, the Web Publishing Engine treats all searches as and searches. To perform an or search, youd use a URL like this one:

[View full width]

Here you supply two search criteria. You also need to supply the field-level operator for each search field. In both cases, you e performing a less-than search, so you need to specify an operator of it for each field. The new element in the query string is the -lop parameter, which stands for logical operator. -lop can have a value of and (the default) or or (the one we e using here). The -lop parameter here instructs the Web Publishing Engine to treat the search as an or search.

Note

In FileMaker proper, you can construct a search thats a complex mixture of and and or searches by entering multiple Find requests, each with more than one field filled in. Such searches can readily be reproduced with Custom Web Publishing: The -lop command can be applied only to all the search fields taken together. There is also no way to invoke the additional FileMaker search options of Constrain or Extend Found Set.

Specifying a Sort Order for Search Results

When you make a request to the Web Publishing Engine, you can specify how the results should be sorted. You can specify one or more fields to sort on, as you can in the regular FileMaker application, and you can specify whether each sort field should be sorted in ascending or descending order. Consider a URL that will find all records in the Animal table, and ask that the records be sorted by name:

http://192.168.101.100/fmi/xml/fmresultset.xml?-db=Animal&-lay=web&-sortfield.1=name&-findall

The new query string command here is called -sortfield. Youll notice we also added the suffix .1 to this parameter. This indicates the sort fields precedence. The concept of precedence is meaningful only if you have more than one sort field, as youll see in a moment. Despite this fact, you can omit the sort precedence, even for a one-item sort, or the records won be sorted at all.

Suppose that you wanted the records to be sorted by gender, and within each gender to be sorted by current weight from highest to lowest. Youd do that like this:

[View full width]

Here two sort fields are specified. The first sort is by gender, the second by weight_current. Theres also a new parameter, called -sortorder. Like -sortfield, -sortorder also takes a numeric suffix. Here, its used to indicate which sort field is being referred to. By default, each field will be sorted in ascending order. If you supply a value of descend for the second sort field, you ensure that the animals will be sorted, within each gender group, from heaviest to lightest.

Applications of Custom Web Publishing with XML

The current section shows how to use the Web Publishing Engine to query a database and publish the results as raw XML in one of several XML grammars. But what use is this capability, exactly?

Well, the most obvious significant use is to allow FileMaker to act as a web service provider. In Chapter 22, "FileMaker and Web Services", we cover how to use FileMaker to pull data from other web services on the Internet. But FileMaker can also act as a web service. If you provide a web service client with an appropriate URL, remote services and programs can query your FileMaker database via the Web Publishing Engine and extract whatever information you choose to let them see.

Additionally, the URL query syntax discussed in this section is also at the heart of the more sophisticated form of Custom Web Publishing thats made possible by the application of XSLT stylesheets, which is the topic of the next section.