.. _wfs_server: ***************************************************************************** WFS Server ***************************************************************************** :Author: Jean-François Doyon :Contact: jdoyon at nrcan.gc.ca :Author: Jeff McKenna :Contact: jmckenna at gatewaygeomatics.com :Revision: $Revision$ :Date: $Date$ :Last Updated: 2006/10/13 .. contents:: :depth: 2 :backlinks: top Introduction ============ A WFS ( Web Feature Service ) publishes feature-level geospatial data to the web. This means that instead of returning an image, as MapServer has traditionally done, the client now obtains fine-grained information about specific geospatial features of the underlying data, at both the geometry AND attribute levels. As with other OGC specifications, this interface uses XML over HTTP as it's delivery mechanism, and, more precisely, GML (Geography Markup Language), which is a subset of XML. WFS-Related Information ----------------------- Here are some WFS related links (including a newly added OGC services workshop with MapServer). Since these are highly detailed technical specifications, there is no need to read through them in their entirety to get a MapServer WFS up and running. It is still recommended however to read them over and get familiar with the basics of each of them, in order to understand how it all works: - The `OGC Web Feature Service Implementation Specification`_. - The `Geography Markup Language Implementation Specification`_. - MapServer `OGC Web Services Workshop package`_. Working knowledge of MapServer is of course also required. Software Requirements --------------------- In order to enable MapServer to serve WFS, it MUST be compiled against certain librairies: - PROJ.4: The reprojection library. Version 4.4.3 or greater is required. - GDAL/OGR: I/O support libraries. Version 1.1.8 or greater is required. Please see the MapServer :ref:`UNIX Compilation and Installation HowTo ` for detailed instructions on compiling mapserver with support for these libraries and features. For Windows users, the `MS4W`_ installer comes ready to serve both WFS and WMS. Version of GML Supported ------------------------ MapServer can output both GML2 and GML3. By default MapServer serves GML2. You can test this by adding an 'OUTPUTFORMAT' parameter to a GetFeature request, such as: - `GML2 request output`_ - `GML3 request output`_ For a detailed discussion on the versions supported, see `bug#884`_. Configuring your MapFile to Serve WFS layers ============================================ Much as in the WMS support, WFS publishing is enabled by adding certain magic METADATA keyword/value pairs to a MapFile. MapServer will serve and include in its WFS capabilities only the layers that meet the following conditions: - Data source is of vector type (Shapefile, OGR, PostGIS, SDE, SDO, ...) - LAYER NAME must be set. Layer names must start with a letter when setting up a WFS server (layer names should not start with a digit or have spaces in them). - LAYER TYPE is one of: LINE, POINT, POLYGON - LAYER DUMP parameter set to TRUE - The "wfs_onlineresource" metadata: The wfs_onlineresource metadata is set in the map's web object metadata and specifies the URL that should be used to access your server. This is required for the GetCapabilities output. If wfs_onlineresource is not provided then MapServer will try to provide a default one using the script name and hostname, but you shouldn't count on that too much. It is strongly recommended that you provide the wfs_onlineresource metadata. See section 12.3.3 of the `WFS 1.0.0 specification`_ for the whole story about the online resource URL. Basically, what you need is a complete HTTP URL including the http:// prefix, hostname, script name, potentially a "map=" parameter, and and terminated by "?" or "&". Here is a valid online resource URL: :: http://my.host.com/cgi-bin/mapserv?map=mywfs.map& By creating a wrapper script on the server it is possible to hide the "map=" parameter from the URL and then your server's online resource URL could be something like: :: http://my.host.com/cgi-bin/mywfs? This is covered in more detail in the "More About the Online Resource URL" section of the :ref:`WMS Server ` document. Example WFS Server Mapfile -------------------------- The following is an example of a bare minimum WFS Server mapfile. Note the comments for the required parameters. .. code-block:: mapfile NAME "WFS_server" STATUS ON SIZE 400 300 SYMBOLSET ../etc/symbols.sym EXTENT -2200000 -712631 3072800 3840000 UNITS METERS SHAPEPATH "../data" IMAGECOLOR 255 255 255 FONTSET ../etc/fonts.txt WEB IMAGEPATH "/ms4w/tmp/ms_tmp/" IMAGEURL "/ms_tmp/" METADATA "wfs_title" "GMap WFS Demo Server" ## REQUIRED "wfs_onlineresource" "http://127.0.0.1/cgi-bin/mapserv.exe?" ## Recommended "wfs_srs" "EPSG:42304 EPSG:42101 EPSG:4269 EPSG:4326" ## Recommended "ows_schemas_location" "http://ogc.dmsolutions.ca" ## Optional END END PROJECTION "init=epsg:42304" END LAYER NAME "province" METADATA "wfs_title" "Provinces" ## REQUIRED "gml_featureid" "ID" ## REQUIRED "gml_include_items" "all" ## Optional (serves all attributes for layer) END TYPE POLYGON STATUS ON DATA province PROJECTION "init=epsg:42304" END DUMP TRUE ## REQUIRED CLASS NAME "Canada" STYLE COLOR 200 255 0 OUTLINECOLOR 120 120 120 END TEMPLATE "ttt_query.html" END END # Layer END # Map File Rules for Handling SRS in MapServer WFS --------------------------------------- Contrary to WMS, the OGC WFS specification doesn't allow a layer (feature type) to be advertised in more than one SRS. Also, there is no default SRS that applies to all layers by default in the OGC WFS spec. However, it is possible to have every layer in a WFS server advertised in a different SRS. Here is how MapServer decides the SRS to advertise and use for each layer in your WFS: - If a top-level map SRS is defined* then this SRS is used and applies to all layers (feature types) in this WFS. In this case the SRS of individual layers is simply ignored even if it's set. - If there is no top-level map SRS defined* then each layer is advertised in its own SRS in the capabilities. - By "SRS is defined", we mean either the presence of a PROJECTION object defined using an EPSG code, or of a "wfs_srs" metadata at this level. Note that at the map top-level the "wfs_srs" metadata value takes precedence over the contents of the :ref:`PROJECTION` block. At the layer level, if both the wfs_srs metadata and the PROJECTION object are set to different values, then the wfs_srs metadata defines the projection to use in advertising this layer (assuming there is no top-level map SRS), and the PROJECTION value is assumed to be the projection of the data. So this means that the data would be reprojected from the PROJECTION SRS to the one defined in the wfs_srs metadata before being served to WFS clients. Confusing? As a rule of thumb, simply set the wfs_srs at the map level (in web metadata) and never set the wfs_srs metadata at the layer level and things will work fine for most cases. Test Your WFS Server -------------------- Validate the Capabilities Metadata ********************************** OK, now that we've got a mapfile, we have to check the XML capabilities returned by our server to make sure nothing is missing. Using a web browser, access your server's online resource URL to which you add the parameter "REQUEST=GetCapabilities" to the end, e.g. http://www2.dmsolutions.ca/cgi-bin/mswfs_gmap?SERVICE=WFS&VERSION=1.0.0&REQUEST=getcapabilities If everything went well, you should have a complete XML capabilities document. Search it for the word "WARNING"... MapServer inserts XML comments starting with "