Web Services Manager exposes your FileMaker scripts as SOAP Web Services. You use a FileMaker-based control panel to configure which scripts should be exposed, how parameters should be passed to them as input, and which fields will be returned as the output.
Once you have installed and configured Web Services Manager, any SOAP compatible software (such as Java, .NET, Flash, PHP, Ruby, Python, C++, or FileMaker itself using the Nexus Web Services plugin - http://www.fmnexus.com/products/webservices/ ) will be able to trigger FileMaker scripts without having to know anything about FileMaker Pro. The SOAP Web Services published by the Web Services Manager are indistinguishable from any other SOAP server.
Web Services Manager is designed with performance and scalability in mind. It triggers scripts by communicating directly with the FileMaker Web Publishing XML gateway, bypassing intermediary layers such as the FileMaker PHP API or FX.PHP. Because of this, there is no maximum limit on the number of records that can be returned by the FileMaker script.
That's all that is needed for basic installation and configuration. Refer to the tooltips on the other fields in the settings form if you would like to customize them. Next, let's test to make sure everything is working correctly.
//Before define( 'HOST', 'localhost' ); //Do not edit this without first consulting the support staff at 360Works //After define( 'HOST', 'localhost:8080' ); //Do not edit this without first consulting the support staff at 360Works
When you first open the Web Services Manager database, it will run for 2 hours in demo mode. Demo mode is fully functional, with no limitations. You can start a new 2 hour demo mode by clicking the 'Start Demo Mode' button in the 'Registration' section. You can also enter your license key information on this screen to switch from demo mode to registered mode, where it will no longer time out after 2 hours.
You may use any SOAP compatible software to test these operations. 360Works provides a general purpose SOAP client that you can use for testing, which can be downloaded from http://www.360works.com/soap-client/ . Our documentation will assume that you are using the 360Works SOAP client. After it downloads, start up the SOAP Client testing software by double-clicking 'SOAPClient.jar'. If you are on Windows and you do not have the Java Development Kit (JDK) installed, you'll get an error message "JDK is not installed, or could not be located". You can download the JDK from Sun at http://java.sun.com/javase/downloads/?intcmp=1281. Mac OS X comes with the JDK pre-installed. Keep in mind that you can use any SOAP compatible software to test the web services; we are just providing one that we have written for your convenience.
Web Services Manager can publish any script from any database running on your server as a SOAP web service. By default, it enables 3 scripts from the 'WSM Examples' file. You can open that file to see how those scripts are written. The scripts in the example file are:
In order for any web service client to communicate with your server, you'll need to tell the client what the WSDL (Web Services Description Language) URL is. You can view this by clicking on the 'Services' button along the top of the window. There is an overall URL for all of the services, or you can select the URL for a specific service. Click on the pasteboard icon to the left of the URL to copy it to the clipboard. Then switch to the SOAP Client, paste the WSDL URL, and click the 'Retrieve button' (You can also just click the hyperlink by the WSDL to view it in your browser. This will work in Internet Explorer or Firefox, but Safari does not display XML data correctly).
Select which operation you want from the pulldown menu. Enter any necessary parameters and then hit 'submit' to trigger the script. The result object is displayed. You may also switch to the 'XML Sent' and 'XML Received' tabs to see the underlying XML SOAP communication.
Try switching to the 'DivideTwoNumbers' operation and pass in 0 as the divisor. You should see an error message about dividing by zero. Later, when we review how to write your own scripts, we will talk about generating custom error messages like this.
XML Web Services have their own terminology, which may be new to FileMaker developers. Here is a quick overview of some of the terms you'll see in this documentation, and when talking to other developers who will be communicating with Web Services Manager:
The example scripts that come with Web Services Manager are defined in the 'WSM Examples.fp7' database. However, you can publish any script from any FileMaker database as a Web Service operation. To publish your own FileMaker scripts as SOAP Web Services, follow these steps:
At this point, you should be able to execute your newly added script as a SOAP Web Service, using the 360Works SOAP client as described in the 'Testing the installation' section above.
If you leave the 'Get Parameters by Name' box unchecked, then the parameters will be passed to you as a return separated list. You can use the GetValue() function to easily grab the parameter data. However, this has some limitations: For one thing, the parameter data itself cannot contain return characters. For another thing, it's easy to mix up the parameters, since the order in the return separated list must match the order of the parameters.
Checking the 'Get Parameters by Name' will pass the parameters to you in an XML format, like this:
<firstName>Jesse</firstName><lastName>Barnum</lastName>
This is a more robust way to pass parameters, since they can contain return characters, and the order is not important, which makes it less prone to bugs. Here is a FileMaker custom function for reading the XML-style parameters, which takes a single parameter: 'paramName'
Let ( [
scriptParameter = Get(ScriptParameter);
openElement = "<" & paramName & ">";
closeElement = "</" & paramName & ">" ;
startPos = Position (scriptParameter ; openElement ; 1; 1) + Length (openElement);
endPos = Position (scriptParameter ; closeElement ; startPos; 1)] ;
Middle (scriptParameter ; startPos ; endPos - startPos)
)
Web Services Manager automatically provides certain error reporting for you automatically.
However, your script may want to provide custom error reporting. For example, the parameters may be invalid (such as the division by zero in the example script), or you may require a plugin on the server that is not installed. In order to return your own custom error messages from your script, create a new layout called 'WebSvcMgrError'. This layout can be based on any table, but the table must contain at least one record! Put a single global field onto this layout (the field can be named anything you like). Have your script switch to this layout, make sure that you have a found set of at least one record, set the global field to the error you want to report, and then exit the script. The Web Services Manager will report this as a SOAP Fault to the requesting client.
The layout that you select for each operation is the output that will be returned from the web service. If multiple operations are set to return the same layout, that layout will be represented as a single XML schema type. This is more efficient than having a separate output layout for each possible operation. Especially for SOAP clients like Java that generate stubs representing all the object types for the web service, sharing the same layout across multiple operations will simplify the programming for the client of your web service.
Layouts may contain portals. This is valid, and portal rows will be returned as nested XML elements.
If you wish to build a Web service operation with a more complex input structure, you may specify a custom XML schema for that operation. An example use case would be the creation of a Web service operation that allows the Web service client to add several records to a FileMaker database at a time.
For any Web service operation, you may specify a custom XML schema by checking the box labeled Use Custom XML Schema found on the layout where you define an operation. Checking this box replaces the portal used to enter input parameters with a text box. In this box, you may enter the raw xml fragment that defines the custom schema you wish to appear in the WSDL. You are responsible for making sure the XML fragment is well-formed.
The XML below is a custom XML schema fragment that defines a Web service operation called AddPerson and two associated complex types, ArrayOfPerson and Person. Comments are included for further clarification; you do not need these in practice.
<!--The AddPerson element contains a single element, ArrayOfPerson, which is of type ArrayOfPerson.-->
<element name="AddPerson">
<complexType>
<sequence>
<element name="ArrayOfPerson" minOccurs="1" maxOccurs="1" type="db2:ArrayOfPerson"/>
</sequence>
</complexType>
</element>
<!--The ArrayOfPerson complex type contains one or more elements named Person, each of which are of type Person.-->
<complexType name="ArrayOfPerson">
<sequence>
<element name="Person" type="db2:Person" minOccurs="0" maxOccurs="unbounded"/>
</sequence>
</complexType>
<!--The Person complex type contains three elements of type string: FirstName, LastName and EmailAddress.-->
<complexType name="Person">
<sequence>
<element name="FirstName" type="xsd:string"/>
<element name="LastName" type="xsd:string"/>
<element name="EmailAddress" type="xsd:string"/>
</sequence>
</complexType>
The script parameter for any script that underlies a Web service operation where custom XML schema support has been enabled will echo the raw XML request posted by the Web service client over HTTP. This means it is up to you to parse the XML within the FileMaker script.
The XML below represents an example SOAP request that satisfies the example schema from the previous section. This request might be used to add two new records to the database, one for John Doe and another for Jane Doe.
<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/"> <Body>
<AddPerson xmlns="http://360works.com/TestFile">
<ArrayOfPerson>
<Person>
<FirstName>Jane</FirstName>
<LastName>Doe</LastName>
<EmailAddress>jane@doe.com</EmailAddress>
</Person>
<Person>
<FirstName>John</FirstName>
<LastName>Doe</LastName>
<EmailAddress>john@doe.com</EmailAddress>
</Person>
</ArrayOfPerson>
</AddPerson>
</Body>
</Envelope>
There are two approaches that you can take to configuring access restrictions for the privilege set. These are outlined below:
In this approach, you set the privilege set for no access to anything EXCEPT for executing the scripts and viewing the layouts defined in Web Service Manager. Then you will need to configure those scripts to run with full access. This is a good approach, because it ensures that the only thing the web service can access are the things that the script does that you write, and it also ensures that your script will not fail because it does not have access to do the things it needs to. This approach is only as strong as the security in your script - if your script accesses or changes inappropriate data, FileMaker will not protect you against this. This approach is not effective if your FileMaker data is stored in multiple separate files.
This approach is more time-consuming and tedious, but allows you to centralize access restrictions that will prevent a script error from accessing inappropriate data. You will need to restrict this privilege set to the bare minimum amount of permissions needed to perform the desired tasks. On the other hand, too many restrictions may not allow the web services to run successfully. Here are some guidelines for establishing privilege sets for web services:
If you contact 360Works for support, we may request a copy of your log files to help with troubleshooting problems.
If you are on a Mac, switch to the Finder and select 'Go->Go To Folder...' from the menubar. Type in '/tmp' and hit the 'go' button. You should see a folder open up showing everything in your /tmp folder; the log file is called websvcmgr.log
If you are on Windows XP, the file will be at C:\WINDOWS\TEMP\websvcmgr.log
When you click 'Refresh Available Files' in the Operations section, an error dialog might appear with several suggestions as to how to fix the error. If none of these suggestions seem to work, it could be the File Display Filter setting in the FileMaker Server Admin Console.
Troubleshooting steps
Keep in mind the 'List all databases' setting only effects the ability to populate the 'Refresh Available Files' list. Once you have finished configuring the Web Services Manager to your liking, you can reset the File Display Filter to 'List only the databases each user is authorized to access' if you wish.
If end users are receiving 400 errors when attempting to invoke Web service operations, one cause might be that your server is not configured to allow internal access via localhost. If you cannot or do not want to resolve this issue via the server, you can change a line in the 'websvcmgr.php' file. The following example assumes your server's DNS name is 'http://fmserver.xyz.com'.
//Before define( 'HOST', 'localhost' ); //Do not edit this without first consulting the support staff at 360Works //After define( 'HOST', 'fmserver.xyz.com' ); //Do not edit this without first consulting the support staff at 360Works
There are several ways that you can contact 360Works for support: