GEOSS Banner

Section 2: Introduction to WPS

 

Introduction

  Web Processing Service (WPS) is an OGC (Open Geospatial Consortium) standard, defining how a geospatial calculation/model/process can be discovered and executed in a Service Oriented Architecture (SOA) strategy, by using instances exposed via HTTP-GET,HTTP-POST and SOAP internet protocols. In theory WPS should be able to describe any process, run it using pre-defined input/output and report error and status.

As defined in wikipedia:

... provides rules for standardizing inputs and outputs (requests and responses) for geospatial processing services, such as polygon overlay. The standard also defines how a client can request the execution of a process, and how the output from the process is handled. It defines an interface that facilitates the publishing of geospatial processes and clients’ discovery of and binding to those processes. The data required by the WPS can be delivered across a network or they can be available at the server.

<<Prev T.O.C Next>>


 

WPS defines three operations, two describing service metadata and Input/Output (I/O) and a third to execute/run the process:

  • getCapabilities - Generic WPS instance metadata, list of services in instance

  • describeProcess - Full description I/O of service

  • Execute - Execution of process with provided Inputs and returned a formatted Output

Figure 1 - Basic WPS interaction pattern. In "Towards a Transactional Web Processing Service"

GetCapabilities

GetCapabilities request returns basic service metadata mainly:

  1. Service identification (keywords and abstract describing the service)

  2. Service provider (who provides the service and how to contact the person in charge (name, telephone etc.)

  3. Operation metadata (HTTP GET and POST description and links to operations)

  4. Process offering (List of processes for each process:abstract, identifier and metadata)

  5. Languages supported (Languages supported by the service, normally the default value is English)

  6. WSDL (Web Service Description Language) file location (URL to Web Service Description Language file, allowing for use of service in other SOA structures that support WSDL)

The getCapababilities KVP (Key-Value-Pair) request (using HTTP GET) uses 2 mandatory parameters: REQUEST and SERVICE, as indicate in listing 1:

http://hostname/wpsInstance?
service=WPS&
request=getCapabilities

Listing 1 - getCapabilities KVP request. 

 

The KVP can be translated into an XML request submitted via HTTP POST to the WPS:

<?xml version="1.0" encoding="UTF-8"?>
<ows:GetCapabilities xmlns:ows="http://www.opengis.net/ows/1.1"
xmlns:wps="http://www.opengis.net/wps/1.0.0" xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.opengis.net/ows/1.1 ..\wpsGetCapabilities_request.xsd"
language="en-CA" service="WPS">
 <ows:AcceptVersions>
 <ows:Version>1.0.0</ows:Version>
 </ows:AcceptVersions>
</ows:GetCapabilities>

Listing 2 - getCapabilities XML request.

 

The KVP or XML request shall return an XML response document where the client will be informed of the processes being offered by the WPS instance, with a brief description (Listing 3):

<wps:Process wps:processVersion="1.0">
    <ows:Identifier>intersectBBOX</ows:Identifier>
   <ows:Title>intersection between 2 bounding boxex</ows:Title>
   <ows:Abstract>intersectBBOX calculates the intersection between 2 bounding boxes</ows:Abstract>
</wps:Process>
<wps:Process wps:processVersion="2.0">
   <ows:Identifier>ultimatequestionprocess</ows:Identifier>
   <ows:Title>Answer to Life, the Universe and Everything</ows:Title>
   <ows:Abstract>Numerical solution that is the answer to Life, Universe and Everything. The process is an 
improvement to Deep Thought computer (therefore version 2.0) since it no longer takes 7.5 million years, 
but only a few seconds to give a response, with an update of status every 10 seconds.</ows:Abstract>
</wps:Process>
Listing 3 - Example of list of processes returned from a getCapabilities request.

 

From the list of served processes, a client/user can pick its identifier name and request extended information on the service by using a describeProcess request.

DescribeProcess

The describeProcess request provides means for a client to determine what are mandatory, optional, and default parameters for a particular process, as well as the format of the data inputs and outputs:

http://hostname/wpsInstance?
request=describeProcess&
identifier=reprojectCoords&
service=WPS&version=1.0.0

Listing 4 - Example of a KVP describeProcess for a process identified as "reprojectCoords".

The SERVICE and VERSION are mandatory parameters in the request. The identifier parameter also allows for a generic "all" value that will return an XML response with detail description for all the services offered by the instance.

<DescribeProcess xmlns="http://www.opengis.net/wps/1.0.0"
 xmlns:ows="http://www.opengis.net/ows/1.1" xmlns:xlink="http://www.w3.org/1999/xlink"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://www.opengis.net/wps/1.0.0 ../wpsDescribeProcess_request.xsd"
 service="WPS" version="1.0.0">
 <ows:Identifier>reprojectCoords</ows:Identifier>
 </DescribeProcess>

Listing 5 - XML describeProcess request equivalent to KVP request in listing 3.

The describingProcess response document will return the following information:

  1. Service identification (Title and abstract)

  2. Service storage and status support

  3. Identifier (Service's unique identifier)

  4. Data Inputs

  5. Data Outputs

<wps:ProcessDescriptions
xsi:schemaLocation="http://www.opengis.net/wps/1.0.0
http://schemas.opengis.net/wps/1.0.0/wpsDescribeProcess_response.xsd"
service="WPS" version="1.0.0" xml:lang="en-CA"><wps:ProcessDescription wps:processVersion="1.0" storeSupported="true"
statusSupported="true">
<ows:Identifier>reprojectCoords</ows:Identifier>
<ows:Title>reproject coordinates</ows:Title>
<ows:Abstract>reprojectCoords uses gdaltransform to reproject a list of coordinates from one
projection to another</ows:Abstract>
<ows:Metadata></ows:Metadata>
[..]
   <DataInputs>
     <Input>[..]</Input
     <Input>[..]</Input>[..]
   </DataInputs>
   <ProcessOutputs>
     <Output>[..]</Output>
     <Output>[..]</Output>
     [..]</ProcessOutputs>
</wps:ProcessDescriptions>

Listing 6 - Structure of a describingProcess response document.

Description of Data Input and Process Outputs

  Three types of inputs and outputs are defined in the OGC standard. LiteralData, ComplexData and BoundingBox data.

LiteralData

 LiteralData can be any character string, float, date, etc normally described as Primitive datatype in the W3C XML Schema standard (http://www.w3.org/TR/xmlschema-2/#built-in-primitive-datatypes). The WPS standard also allows the use of UOM (Unit of Measures), default values and AllowedValues (defining a range of allowed values). In case of missing inputs for an optional input the service will use a default value.

For example a describeProcess response maybe contain the following input description (Listing 7):

<Input minOccurs="0" maxOccurs="1"><ows:Identifier>method</ows:Identifier>
 <ows:Title>Interpolation method</ows:Title>
 <ows:Abstract>Interpolation method to be used in a dataset of points</ows:Abstract>
 <LiteralData>
 <ows:DataType ows:reference="xs:string">string</ows:DataType>
 <ows:AllowedValues>
 	<ows:Value>idw</ows:Value>
 	<ows:Value>kriging</ows:Value>
 	<ows:Value>thysson</ows:Value>
 </ows:AllowedValues>
 <DefaultValue>kriging</DefaultValue>
 </LiteralData>

Listing 7 - DescribeProcess response describing LiteralData input of type string indicating allowed values and default value.

The XML in Listing 6 defines that input "method" that is of type string, can have one of the following input values: "idw", "kriging", and "thysson" and if no input is present, "kriging" will be used as the default value.

<Input minOccurs="0" maxOccurs="1">
 <ows:Identifier>BufferDistance</ows:Identifier>
 <ows:Title>Buffer Distance</ows:Title>
 <ows:Abstract>Distance to be used to calculate buffer.</ows:Abstract>
 <LiteralData>
 <ows:DataType ows:reference="http://www.w3.org/TR/xmlschema-2/#float">float</ows:DataType>
 <UOMs>
 	<Default>
 	<ows:UOM>meters</ows:UOM>
 	</Default>
 	<Supported>
 	<ows:UOM>meters</ows:UOM>
 	<ows:UOM>feet</ows:UOM>
 	</Supported>
 </UOMs>
 <ows:AnyValue/>
 <DefaultValue>100</DefaultValue>
 </LiteralData>
 </Input>

Listing 8 - DescribeProcess response of a buffer service that indicates the support of different units of measure (UOM): meters or feet. Input is defined as float, the ows:reference indicates an URI to a W3C document, instead of a schema defintion (xsd:float), this approach is also valid.

 

In this case we have an input that is a float number and whose units can be in meters or feet, if the input is not specified then use 100.0 meters as default.

ComplexData description

  ComplexData type is used to describe vector, raster (or any other data) . There are two ways, how complex data are handled:

  • Embedded in the XML content, for example a GML content inside the ComplexData element or a binary raster data encoded in base64

  • URL reference to the data or service that will provide data

ComplexData content is loosely defined by the WPS schema. This element's content is defined as "xs:anyType", no data format or imposition is defined. Despite it's loose content ComplexData element may contain a MimeType/Encoding/Schema triplet that describes the XML content. (Listing 9).

<Input minOccurs="1" maxOccurs="1">
<ows:Identifier>inputPolygon</ows:Identifier>
<ows:Title>Polygon to be buffered</ows:Title>
<ows:Abstract>GML that describes the polygon to be buffered</ows:Abstract>
<ComplexData>
 <Default>
 <Format>
 <MimeType>application/gml+xml</MimeType>
 <Encoding>UTF-8</Encoding>
 <Schema>http://schemas.opengis.net/gml/3.1.0/base/geometryBasic2d.xsd</Schema>
 </Format>
 </Default>
<Supported>
[..]
</Supported>
</ComplexData>
<Input minOccurs="1" maxOccurs="1">
<ows:Identifier>inputImage</ows:Identifier>
<ows:Title>Input image</ows:Title>
<ComplexData>
 <Default>
 <Format>
 <MimeType>image/tiff</MimeType>
 </Format>
</Input>

  Listing 9 - "Technical Comittee Policies and Procedures: MIME Media Types for GML - OGC 09-144r1".

  Listing 9, describes two complex inputs that are mandatory (minOccurs="1"), that will be identified as inputPolygon and inputImage. ComplexData inputPolygon is a GML3.1.0 content defined in schema geometryBasic2d.xsd and encoded in UTF-8, ComplexData imageImage is a tiff image.

Bounding Box Data description

  Bounding Box, or just BBOX is the third data type and it is used to describe a bounding box area. BBOX is defined in the document "Web Services Common Specification 06-121r3 ". The input description must state the default coordinate reference system (CRS) (normally a URI of the EPSG code system) and other CRS supported.

<Input>
<ows:Identifier>bboxInput</ows:Identifier>
 	<ows:Title>bounding box of dummy polygon</ows:Title>
 	<ows:Abstract>Bounding box of dummy polygon to be used for fast 
                polygon interception calculation</ows:Abstract>
 <BoundingBoxData>
 	<Default>
 <CRS>urn:ogc:def:crs:EPSG:6.6:4326</CRS>
 	</Default>
 	<Supported>
 	<CRSsType>
 		<CRS>urn:ogc:def:crs:EPSG:6.6:4326</CRS>
 		<CRS>urn:ogc:def:crs:EPSG:6.6:4979</CRS>
 	</CRSsType>
 	</Supported>
 </BoundingBoxData>
 </Input>

  Listing 10 - Bounding Box Input description. Coordinate reference system (CRS) is defined as URI.

 

Listing 10 indicates a BBOX input where the default CSR is in geographical projection (lat/long, EPSG:4326) and optionally EPSG:4979 could also be used (which is an alias to EPSG:4326). 

An KVP Execute request with a BBOX input would be like:
...&bboxInput=71.63,41.75,-70.78,42.90,urn:ogc:def:crs:EPSG:6.6:4326 

where bbox=LowerCorner longitude,LowerCorner latitude,UpperCorner longitude,UpperCorner latitude,CRS URI.

Execute

The Execute request is the request that will launch the specified process implemented by the WPS instance. In an Execute request a client must specify:

  1. Process identifier

  2. Input values as defines in the describeProcess

  3. Version and language

  4. Type of Output either:

    1. Stored in the server

    2. Contained inside the XML response

    3. Raw response of single output, dump the result to the client (for example an image)

  5. If the server shall return a status document (synchronous or asynchronous call)

  6. If the input data should be returned in the response document (lineage) .

KVP Execute request
Execute requests tend to be complex (since they have to define I/O and process execution) and should be done in XML. Nevertheless KVP and HTTP GET can be used to run an Execute request and to understand its purpose.

For example the following KVP Execute request executes a service that generates a buffer around a polygon.

http://hostname/wpsInstance?&
request=Execute&
identifier=bufferPolygon&
datainputs=bufferDistance=35;inputPolygon=http%3A%2F%2Flocaldomain%2Fpoylgon.gml
service=WPS&version=1.0.0&
storeExecuteResponse=true&
lineage=true&
status=true 

Listing 11 - Execute request

The SERVICE and VERSION are mandatory parameters like in describeProcess. DATAINPUTS contains the inputs that have the following identification: bufferDistance and inputPolygon

The KVP DATAINPUTS should be encoded using the following rules:

  1. A semicolon (;) shall be used to separate one input from the next

  2. An equal sign (=) shall be used to separate an input name from its value and attributes, and an attribute name from its value

  3. An at-symbol (@) shall be used to separate an input value from its attributes and one attribute from another.

  4. All field values and attribute values shall be encoded using the standard Internet practice for encoding URLs (http://en.wikipedia.org/wiki/Url_encoding)

Based on Listing 7 and the describeProcess XML reponse the bufferDistance description in Execute could be:

....bufferDistance=35@datatype=xs:integer@uom=meter 

As indicated in the ComplexData description an input can be embedded in the Execute request or referenced as in URL that will be used by the WPS to fetch the data content and process it, an extended example of inputPolygon based on Listing 7:

inputPolygon=http%3A%2F%2Ffoo%2Flocaldomain%2Fpolygon.gml@
format=application%2Fgml%2Bxml@encoding=UTF-8@
schema=geometryBasic2d.xsd

Or in a more human friendly form:

inputPolygon=http://localdomain/polygon.gml@
format=application/gml+xml@
encoding=UTF-8@schema=geometryBasic2d.xsd

 

storeExecuteResponse and status parameters
Geo-processes are computational intensive, and might require a considerable amount of time to run.,eventually reaching a point where they take more time than allowed for an HTTP connection to remain open (while doing the execute request). WPS uses a pull methodology (http://en.wikipedia.org/wiki/Pull_technology) to deal with time-consuming processes. It's up to the client to initiate the Execute request and then to constantly query (pull) the server for an update/content.

The pull strategy is defined by two parameters during the Execute request: storeExecuteReponse and status.

If storeExecuteResponse=true, the server will store the execute response document in a web accessible URL that the client will use to pull the document. When making the request the service shall respond immediately with an URL to the client. This URL will be used to determine the status of the process and/or pull the process output when concluded.

If status=true, then the server will constantly update the stored document with on-going reports on the status of execution (for example percentage concluded). If status=false then the service shall not update the execute response document until the process either completes successfully or fails. In case status=true and storeExecuteResponse=false then a service exception shall be reported.

Listing 10 defines: storeExecuteResponse=true&status=true, in this case the client will recieve an URL with the document location, and its content will be updated as the process runs in the server.

Lineage

A response execute document may contains the input used to run the WPS. This is normally referred as lineage. To request a lineage structure in the response document the KVP GET should contain lineage=true.

Lineage is an independent KVP parameter that is NOT associated with responseDocument properties.

Response Document

The sort of response document from an execute request can be manipulated during the client request. A client may request for only a specific output mimetype encoding schema or for the output to be given as reference (an URL pointing to the output).

In a KVP request, the parameter RESPONSEDOCUMENT will define the sort of output returned:

http://hostname/wpsInstance?&
request=Execute&
identifier=bufferPolygon&
datainputs=bufferDistance=35;inputPolygon=http%3A%2F%2Flocaldomain%2Fpoylgon.gml
service=WPS&version=1.0.0&
storeExecuteResponse=true&
lineage=true&
status=true&
responsedocument=buffer=@asreference=true
Listing 12 - Example of a request for a specific output (identifier as buffer) as reference (URL).

 

The responsedocument syntax follows generic datainputs encoding rules. If asReference=true then the output will be returned as a reference (URL) that the client may use to pull the output.

Other output attributes can be used to manipulate an output, for example a buffer result could be returned as an XML structure or burned into a raster image (if allowed by the service). E.g:

responsedocument=buffer=@mimetype=image/tiff

Or

responsedocument=buffer=@mimetype=application/gml+xml

 

RawResponse

Optionally a single output can be outputted as a raw response, meaning a raw response for an output that will generate a geoTIFF will be the image itself without any WPS Response document. The raw response is obtained by using parameter RAWDATAOUTPUT instead of RESPONSEDOCUMENT. 

http://hostname/wpsInstance?&
request=Execute&
identifier=bufferPolygon&
datainputs=bufferDistance=35;inputPolygon=http%3A%2F%2Flocaldomain%2Fpoylgon.gml
service=WPS&version=1.0.0&
storeExecuteResponse=true&
lineage=true&
status=true&
rawdataoutput=buffer=@mimetype=image/tiff

Listing 13 - Raw output request for a buffer in a tiff format

XML Execute request

XML Execute request mimics the KVP Execute request, with identical attributes and functionalities. The XML document can be divided into 3 sections:

storageExecuteDocument and status are defined as attributes of the response document:

  1. Service identification, language and version request

  2. Data inputs

  3. Structure of response document

Listing 13 is an example of an Execute request for a process named bufferProcess

<wps:Execute service="WPS"version="1.0.0"language="en-CA"
xmlns:wps="http://www.opengis.net/wps/1.0.0" 
xmlns:ows="http://www.opengis.net/ows/1.1" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="http://www.opengis.net/wps/1.0.0/wpsExecute_request.xsd">
<ows:Identifier>bufferProcess</ows:Identifier>

Listing 14 - XML section with service identification and Execute request to WPS instance.

 

Data inputs follow the complexdata description, allowing for embedded data or URL reference to be used. Listing 15.

<wps:DataInputs> 
<wps:Input> 
<ows:Identifier>inputPolygon</ows:Identifier> 
<ows:Title>Input polygon for buffer calculation</ows:Title> 
   	<wps:Reference xlink:href="http://localdomain/polygon.gml" /> 
/wps:Input>

Listing 15 - Example of a complexData input passed by Reference

The usage of xlink:href allows for the usage of unquoted URLs.

<wps:DataInputs> 
<wps:Input> 
<ows:Identifier>inputPolygon</ows:Identifier> 
<ows:Title>Input polygon for buffer calculation</ows:Title> 
  <wps:Data>
 <wps:ComplexData mimeType="application/xml+gml" encoding="UTF-8" 
schema="http://schemas.opengis.net/gml/3.1.1/base/geometryBasic2d.xsd">
	<gml:Polygon>
	<gml:outerBoundaryIs>
	<gml:LinearRing>
	<gml:coordinates>96331.843041083571734,202504.810803000174928....
                         96331.843041083571734,202504.810803000174928
	</gml:coordinates>
	</gml:LinearRing>
	</gml:outerBoundaryIs>
	</gml:Polygon>
</wps:ComplexData>
</wps:Data>
</wps:Input> 

Listing 16 - Example of complexData inputs embedded in the WPS Execute request

Data and Reference elements are used to determine if the content is embedded or passed as reference.

 

The third section of the Execute request is optional and if present, it defines what the response document should contain,. If the status=true or storeExecuteDocument=true, data format or lineage should be returned.

<wps:ResponseForm> 
            <wps:ResponseDocument lineage="true" storeExecuteResponse="true" status="true"> 
                <wps:Output asReference="true" mimeType="application/xml+gml"> 
                    <ows:Identifier>buffer</ows:Identifier> 
                </wps:Output>
            </wps:ResponseDocument> 
 </wps:ResponseForm>

Listing 17 - Response document section of WPS Execute request.

 

Locale definitions

WPS offers multilingual capabilities in metadata description. A getCapabilities request shall return the supported languages in the server.

<wps:Languages>
<wps:Default>
	<ows:Language>en-CA</ows:Language>
</wps:Default>
<wps:Supported>
<ows:Language>en-CA</ows:Language>
	<ows:Language>fr-CA<ows:Language>
	<ows:Language>fr-FR<ows:Language>
	<ows:Language>es-ES</ows:Language
	<ows:Language>pt-PT</ows:Language>
	<ows:Language>pt-BR</ows:Language>
</wps:Supported>
</wps:Languages>

Listing 18 - Example of languages supported by a multilingual server.

Language code description follows standard RFC 4646. The client may use the attribute LANGUAGE with the code language to obtain metadata description (describeProcess) in the desired language.

 

WPS Exceptions

WPS execution may encounter errors that will be returned to the client, using specific exception code according to the error. Some errors may indicate a locator parameter of the error. 
<?xml version="1.0" encoding="utf-8"?>
<ows:ExceptionReport version="1.0.0" 
xmlns:ows="http://www.opengis.net/ows/1.1" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="http://www.opengis.net/ows/1.1 http://schemas.opengis.net/ows/1.1.0/owsExceptionReport.xsd">
        <ows:Exception exceptionCode="InvalidParameterValue" locator="NonExistingService"/>
</ows:ExceptionReport>

Listing 19 - WPS exception of a describeProcess request using a non-existing service (request=DescribeProcess&identifier=NonExistingService&service=WPS&version=1.0.0).

 

WPS instances have a minimum of 4 exceptionCodes (WPS defines 8 exceptionCodes in total):

-MissingParameterValue --> The request does not include a parameter value or a default cannot be found

-InvalidParameterValue --> The request contains an invalid parameter value

-NoApplicableCode --> Generic exception, no other code could be applied

-NotEnoughStorage --> The server does not have enough space available

 

SOAP binding

SOAP (Simple Object Access Protocol) is a messaging framework, meaning, a structured way to pass, explain and process a message. The expression " SOAP message" is normally referring to some sort of XML content that is associated with a SOAP header than in turn is wrapped by a SOAP envelope. This SOAP structure is normally transported by HTTP, nevertheless nothing prevents the use of protocols like: FTP,SSH,SMTP etc.

 

Figure 2 - Generic SOAP structure.

 

SOAP in WPS is normally used as simple wrapper (encapsulation) around the XML requests (following the SOAP document-style encoding), and currentely different WPS frameworks have different implementation levels.

A WPS Getcapabilities request using SOAP 1.1 would be as follows:

<?xml version="1.0" encoding="UTF-8"?>
 <!--
 Equivalent GET request is
 http://foo.bar/foo?Service=WPS&Version=1.0.0&Request=GetCapabilities&Language=en-CA
 -->
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
 <SOAP-ENV:Body>
     <wps:GetCapabilities xmlns:ows="http://www.opengis.net/ows/1.1"
      xmlns:wps="http://www.opengis.net/wps/1.0.0"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://www.opengis.net/wps/1.0.0 ../wpsGetCapabilities_request.xsd"
      language="en-CA" service="WPS">
           <wps:AcceptVersions>
               <ows:Version>1.0.0</ows:Version>
           </wps:AcceptVersions>
     </wps:GetCapabilities>
 </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Listing 20 - Example of a getCapabilities request using SOAP1.1 wrapper.

 

The same request can be wrapped in SOAP 1.2 wrapper

<?xml version="1.0" encoding="UTF-8"?>
 <!--
 Equivalent GET request is
 http://foo.bar/foo?Service=WPS&Version=1.0.0&Request=GetCapabilities&Language=en-CA
 -->
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
 <soap:Body>
     <wps:GetCapabilities xmlns:ows="http://www.opengis.net/ows/1.1"
      xmlns:wps="http://www.opengis.net/wps/1.0.0" xmlns:xlink="http://www.w3.org/1999/xlink"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://www.opengis.net/wps/1.0.0 ../wpsGetCapabilities_request.xsd"
      language="en-CA" service="WPS">
           <wps:AcceptVersions>
               <ows:Version>1.0.0</ows:Version>
           </wps:AcceptVersions>
     </wps:GetCapabilities>
 </soap:Body>
</soap:Envelope>

 Listing 21 - Example of a getCapabilities request using SOAP1.2 wrapper.

 

SOAP header is an extension mechanism that provides a way to pass information in SOAP messages that is not application payload (therefore WPS request parameters can not be expressed in the SOAP-header). Such "control" information includes, for example, passing directives or contextual information related to the processing of the message. This allows a SOAP message to be extended in an application-specific manner (from: http://www.w3.org/TR/soap12-part0/#L1161). An example of the extension mechanism is a basic authentication using the SOAP header:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
 <SOAP-ENV:Header>
   <h:BasicAuth xmlns:h="http://soap-authentication.org/basic/2001/10/"
   SOAP-ENV:mustUnderstand="true">
   <h:Name>bacon</h:Name>
   <h:Password>eggs</h:Password>
   </h:BasicAuth>
 </SOAP-ENV:Header>
<SOAP-ENV:Body>
<wps:GetCapabilities> ......</wps:GetCapabilities>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Listing 22 - Example of a SOAP1.1 header authentication structure. Source: http://www.whitemesa.com/soapauth.html

 

The mustUnderstand="true" (or mustUnderstand="1") mandates that the containing header block must be parsed and understood by the system, in this case the authentication has to be processed before any the SOAP Body content is processed.

SOAP support is applicable to all WPS operations (getCapabilities, describeProcess and Execute), but Execute request only allow SOAP usage when the output is a ResponseDocument, a request for a specific RawDataOutput shall generate a SOAP error.

 

The Execute request may exist in two forms:

  • Complete XML request and indicate in listings 13-16.
  • Process name and I/O encoded as an element in the SOAP body

The process name and I/O encoded as elements in the SOAP body facilitates the usage of WPS inside WSDL. The process name shall be turned into an element in the SOAP body by prepending the text "ExecuteProcess_"

and the I/O names shall be turned into elements, e.g:

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
 <soap:Body>
 <ExecuteProcess_BufferProcess>
 <InputPolygon>http://rsg.pml.ac.uk/wps/testdata/simplePoly.gml</InputPolygon>
 <BufferDistance>400</BufferDistance>
 </ExecuteProcess_DummyProcess>
 </soap:Body>
 </soap:Envelope>

Listing 23 - Example of a WPS request with process name an I/O encoded inside the SOAP Body content.

 

WPS 1.0.0 document is one clear in some aspects of the SOAP Body encoding, for example there is no information on how to encode WPS attributes (e.g status) or how to deal with async calls to the service.

The SOAP standard supports for fault reporting, by including a Fault element inside the Body element. This Fault element contains a mandatory Code and Reason elements, these mandatory elements contain the error code and an extended explanation (respectively) . The Code element reports a specific SOAP error defined in the specification, in case of WPS this value is "soap:Server". WPS exceptionReport shall be contained inside an optional Detail element.

<soap:Envelope xmlns:soap=http://www.w3.org/2003/05/soap-envelope xmlns:ows=http://www.opengis.net/ows/1.2>
  <soap:Body>
    <soap:Fault>
        <soap:Code>
	<soap:Value>soap:Server</soap:Value>
        </soap:Code>
             <soap:Reason><soap:Text>A server exception was encountered.<soap:Text></soap:Reason>
        <soap:Detail>
	<ows:ExceptionReport>
	         ...
	</ows:ExceptionReport>
        </soap:Detail>
     </soap:Fault>
   </soap:Body>
</soap:Envelope>

Listing 24 - SOAP1.2 fault exception containing a WPS Exception Report.

 

WSDL

  WSDL stands for Web Services Description Language. WSDL is a document written in XML that describes a Web service. It specifies the location of the service and the operations (or methods) the service exposes basically its an XML document that contains more or less the same information as GetCapabilities/DescribeProcess, but in a generalist way without the use of OGC's nomenclature and standards. The problem with WSDL is that we have to "explain" everything to system, meaning we have to explain all WPS structure.

In theory having a WPS instance providing WSDL information should allow for it to be used as a generalist web service in any programming environment or orchestration language like BPEL (Business Process Execution Language).

 

Figure 3 - Representation of concepts defined by WSDL 1.1 and WSDL 2.0 documents.

WSDL implementation is described in the WPS spec as a "best practices" avoiding the specification of WSDL contents and interaction with WPS attribute and I/O. Therefore different WPS frameworks have different WSDL implementations strategies.

A WPS supporting WSDL shall return a generic WSDL document, describing all processes, when submitting the following KVP request:

http://hostname/wpsInstance?WSDL

In addition each individual service may contain its own WSDL description that is returned when submitting the following KVP request:

http://hostname/wpsInstance/identifier[/service.soap]?WSDL

Where identifier is the WPS process identifier and the [/service.soap] is an optional URL section that points to the root of the HTTP SOAP requests.

<<Prev T.O.C Next>>

Tag
none

Files (0)

 
You must login to post a comment.