WebServicesManager

Web Services Manager installation has it's own page; head there first for installation help.

Conceptual Overview

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.

System Requirements

• You must be running FileMaker Server or Server Advanced with version 11 or later.
• The Web Publishing Engine must be enabled

NOTE: If you are using FMS 17 or later, XML Web Publishing is turned off by default and needs to be turned on using the fmsadmin utility. This is separate from the toggle switch in the admin console. Please follow the instructions here in order to turn on XML Web Publishing.

Installation

• Deploy the 'Web Services Manager.fp7' (or Web Services Manager.fmp12) and 'WSM Examples.fp7' (or WSM Examples.fmp12) files onto your FileMaker Server, as you would any normal FileMaker database.
• Open the database 'Web Services Manager' as a guest of the FileMaker Server. The username and password are user/pass. You will need to change the password to something else; be sure to keep a record of the new password.
• After you change the password, edit the 'websvcmgr.php' file and change line 10 of that file to reflect the new password.
• Copy the 'websvcmgr.php' file into your Web Server document root, where you would normally put PHP files for use with the Web Publishing.
  • On OS X, this is '/Library/FileMaker Server/HTTPServer/htdocs' for FileMaker Server 13 or later, and '/Library/WebServer/Documents' for older versions.
  • On Windows, this is 'C:\Program Files\FileMaker\FileMaker Server\HTTPServer\conf' for FileMaker Server 13 or later, or 'C:\Inetpub\wwwroot' for older versions
• Be sure that any databases you use for web service publishing have the fmxml and fmphp extended privileges enabled.
• If you are using FileMaker Server 17 and have not already, PHP and XML need to be enabled for WSM to work. Open Terminal (Mac) or CMD/PowerShell (Win) and type the command: fmsadmin set cwpconfig enablephp=true and then the command fmsadmin set cwpconfig enablexml=true. You will need to restart FileMaker services after doing so.

Required configuration

• In the Web Services Manager database, click the 'Settings' button at the top of the window. Set the 'Server Host URL' in the Settings page to point to the computer running the FileMaker Web Publishing Engine. For example, if your server's DNS name is fmserver.xyz.com, you would enter 'http://fmserver.xyz.com'.

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.

Configuration on non-standard ports

• By default, the Web Services Manager assumes that the FileMaker Server Web Publishing Engine is set to run on port 80. If you wish to use another port, you must specify it explicitly in the 'Settings' area.
• For example, if your server's DNS name is fmserver.xyz.com and the Web Publishing Engine is set to run on port 8080, you would enter 'http://fmserver.xyz.com:8080'.
• You will also need to make the following modification to the 'websvcmgr.php' file.

//Before
define( 'HOST', '127.0.0.1' ); //Do not edit this without first consulting the support staff at 360Works

//After
define( 'HOST', '127.0.0.1:8080' ); //Do not edit this without first consulting the support staff at 360Works

Demo mode and registration

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.

Testing the installation

You may use any SOAP compatible software to test these operations. We recommend using SoapUI which can be downloaded here.

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:

• 'HelloWorld' simply echoes the string 'Hello World'.
• 'AddTwoNumbers' is an example of about the simplest useful script you can write. It shows how to take multiple input parameters as a return-separated list and process those in your script.
• 'DivideTwoNumbers' builds on the previous example by including some custom error checking, in the event of division by zero. It also shows how your script can receive parameters as named values, instead of as a return-separated list.

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.

PHP test code

This shows how to use PHP to call the 'AddTwoNumbers' example service on the 360Works server:

<?php
//Prevents WSDL from being cached
$ini = ini_set("soap.wsdl_cache_enabled", 0);

$soap = new SoapClient('http://wpeoffice.360works.com/websvcmgr.php?wsdl&Service=ExampleService');
$lookup = $soap->AddTwoNumbers(array("Addend1" => "3", "Addend2" => "4"));

print_r( $lookup );
?>

Terminology

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:

• An 'operation' (sometimes called a 'method') is a single action. This corresponds directly to a FileMaker script. An operation takes zero or more parameters, calls a FileMaker script, and then returns all of the fields on the current layout in the found set after that script finishes.
• A 'service' is a collection of operations, grouped together by functionality. 360Works Web Service Manager allows you to define multiple services, which can each contain many operations. You can easily enable or disable services with a checkbox. For example, you might have an 'Inventory' service and a 'Shipping' service, or you could choose to combine all operations into an 'Operations' service.
• 'WSDL' is an acronym for a Web Services Description Language. A WSDL is used to describe, in great detail, exactly what operations are available in a service. This detailed description, which can also include user-readable documentation, makes it easy for SOAP-compatible systems to communicate with each other. Although you can send a WSDL file to somebody by any means (e-mail, snail mail, FTP, etc.), they are typically posted online and available at some http URL.

Adding new operations

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:

1. Use FileMaker Pro to connect to the database that has the script you want to publish. It must be hosted on the same server as the 'Web Services Manager' file. Make sure that at least one privilege set has the 'fmphp' and 'fmxml' extended privileges enabled.
2. If you do not already have a layout with the fields that you would like your operation to return, create one. See the 'layouts' section below for more information.
3. If you do not already have a script written that will perform the desired action, write one. See 'Tips on writing your own scripts' and 'Reading script parameters' below for more information.
4. In the 'Web Services Manager', go to the Operations section and click 'Refresh Available' Files.
5. From the pull-down menu of files, pick the file that has the desired script and layout, and click 'Add'. Select that same file from the list of files and click 'New Operation'. If the guest account in that file does not have the 'fmxml' and 'fmphp' extended privileges enabled, you will be prompted to enter a username and password for an account that does have these extended privileges.
6. Fill out the information on the Operation detail page and click 'OK'. Refer to the layout tooltips for more information on these options.
7. Note that if you did not add the operation to a service when you first defined it, the operation appears disabled. This is because it has not yet been added to any services. Click on the 'services' section and add the new operation to a service, or create a new service and add the operation to it.

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.

Tips on writing your own scripts

• Be very careful to only use web compatible script steps. The script will exit prematurely if it encounters a non web compatible script step.
• Be sure to do set error capture[on] before doing a find, because if the find fails, it will keep whatever the current found set is. This is probably not the desired result.

Reading script parameters

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)
)

Error reporting

Web Services Manager automatically provides certain error reporting for you automatically.

• If you check the box to return a single result, and the script results in an empty found set, this will return an error.
• If the SOAP request cannot be authenticated, this will return an error.

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.

Layouts

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.

Specifying a Custom XML Schema

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.

Enabling Custom XML Schema Support

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. Be sure to exclude any xml headers from the fragment.

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>

Reading Script Parameters

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>

Security

• Privilege sets: Although it may be tempting to just have web services run with the 'Data Entry Only' privilege set, which gives it read/write access to all data, that is a bad idea for anything other than early testing or private network access with a group of trusted users. It is a good idea to create a privilege set specifically for the purpose of calling web services, or else have the Web Service run as a guest and configure the guest privilege set to allow the operation to execute.
  • Any operation that accesses sensitive information should be set to 'Run script with username/password from web service SOAP header'. When this option is set, the web service client must supply a username and password which must match a FileMaker account, and will run with the privilege set of that account.
  • The privilege set must have the 'fmxml' extended privilege enabled. If this privilege set is specifically set up for the Web Service (which is recommended), it should not have any other extended privileges enabled.

There are two approaches that you can take to configuring access restrictions for the privilege set. These are outlined below:

Scripts run with full access

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.

Customize privilege set access

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:

• • Set record access to custom privileges, and use a calculation to limit record access to only the records that should be viewable for the web service.
  • Whenever possible, make access read-only. Only use read-write if you want the web service to be able to make modifications to your database.
  • Only allow access to the layouts that are used by the web service.
  • Keep in mind that if a table is read-only, the global fields in it are also read-only. If you want the service to execute a script in a read-only table that needs to set global fields in that table, either make those global fields specifically writable, or consider replacing them with global variables (using the $ or $$ notation introduced in FileMaker Pro 8), which are always writable.
  • If you are using custom error reporting (see above), keep in mind that the error field must be writable to the script, and the layout that is on must be accessible.

Miscellaneous notes

• If your web server is set up with SSL encryption and you would like to encrypt the Web Services, change the http:// to https:// in the Server Host URL setting.

Log files

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 files are called websvcmgr.log and wsmRequest.log.

If you are on Windows, the file will be at C:\WINDOWS\TEMP\websvcmgr.log and C:\WINDOWS\TEMP\wsmRequest.log

Troubleshooting and Support

SOAP Faults Return HTML instead of XML

This may occur when the websvcmgr.php file is hosted using Windows Internet Information Services (IIS). In keeping with the SOAP specification, the Web Services Manager returns an HTTP response code of 500 when a SOAP fault occurs. If IIS is configured to return an error HTML page when it encounters a 500 response code, then you will need to disable this feature in order for the consumer of the Web service operation to receive an XML response when a SOAP fault is triggered.

'Refresh Available Files' Error

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

• Open the FileMaker Server Admin Console.
• Go Configuration -> Database Server -> Security and look for a section called File Display Filter.
• Make sure the radio button is set to 'List all databases'

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.

'Bad Request (Invalid Hostname)' Error

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', '127.0.0.1' ); //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

Is WSM the same thing as the FM Nexus Web Services plugin?

No, in fact these two products complement each other. The 360Works Web Services Manager lets FileMaker Server act as a server for XML Web Service requests, which could come from the FM Nexus plugin (http://fmnexus.com/products/webservices/) or any other XML Web Service client. The FM Nexus plugin is installed on the FileMaker Pro client to access an XML Web Service, which could be published by the 360Works Web Service Manager or any other XML Web Service publisher.

Template:Support