In this primer we will demonstrate how to access and execute a remote prosessing service using the OGC Web Processing Service (WPS) protocol.
Find a WPS server
Find a data web source that hosts a WPS server, Deltares hosts a test server at http://dtvirt5.deltares.nl/wps/?
Request an overview of the capabilities of a WPS server
Ask for what the server has to offer
keyword |
value |
source |
---|---|---|
service |
WPS |
Mandatory WPS standard value |
version |
1.0.0 |
Optional for GetCapabilities |
request |
GetCapabilities |
Mandatory WPS standard value |
language |
Usually 'en' (English) |
Optional |
http://dtvirt5.deltares.nl/wps/? Request=GetCapabilities& Service=WPS
This URL returns an xml file that contains an inventory of the available processes.
Inspect the overview of the content of a WPS server
Look at which WPS processes the server has to offer. For each process there is a tag ows:identifier
with an identifier and title of the process, as shown in the reduced xml file example below:
<wps:Capabilities xmlns:xlink="http://www.w3.org/1999/xlink" 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" service="WPS" version="1.0.0" xml:lang="en-CA" xsi:schemaLocation="http://www.opengis.net/wps/1.0.0 http://schemas.opengis.net/wps/1.0.0/wpsGetCapabilities_response.xsd" updateSequence="1"> <ows:ServiceIdentification> ... </ows:ServiceIdentification> <ows:ServiceProvider> ... </ows:ServiceProvider> ... <ows:HTTP> <ows:Get xlink:href="http://dtvirt5.deltares.nl/wps?"/> <ows:Post xlink:href="http://dtvirt5.deltares.nl/wps"/> </ows:HTTP> ... <wps:ProcessOfferings> <wps:Process wps:processVersion="0.1"> <ows:Identifier>ogrbuffer</ows:Identifier> <ows:Title>Buffer process using OGR</ows:Title> </wps:Process> ... <wps:Process wps:processVersion="1"> <ows:Identifier>constituents</ows:Identifier> <ows:Title>Lookup constituents based on their short name</ows:Title> </wps:Process> <wps:Process wps:processVersion="0.1"> <ows:Identifier>IDT_simple</ows:Identifier> <ows:Title>Interactive Dredge Planning Tool</ows:Title> </wps:Process> <wps:Process wps:processVersion="1"> <ows:Identifier>status_test</ows:Identifier> <ows:Title>echo</ows:Title> <ows:Abstract>Echo server</ows:Abstract> </wps:Process> </wps:ProcessOfferings> ... </wps:Capabilities>
Request a specific process of the WPS server
Where the GetCapabilities request returns a full summary of the server's capatbilities, the DescribeProcess request returns specific information on a single process.
keyword |
value |
source |
---|---|---|
service |
WPS |
Mandatory WPS standard value |
version |
1.0.0 |
Mandatory for DescribeProcess |
request |
DescribeProcess |
Mandatory WPS standard value |
identifer |
process name |
Mandatory parameter |
language |
Usually 'en' (English) |
Optional |
In this exmaple we are going to use the 'constituents' process, below the URL for the DescribeProcess request.
http://dtvirt5.deltares.nl/wps/? request=DescribeProcess& service=wps& version=1.0.0& identifier=constituents
This URL will return an xml file that contains a description of the requested processes.
<wps:ProcessDescriptions xmlns:wps="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 http://schemas.opengis.net/wps/1.0.0/wpsDescribeProcess_response.xsd" service="WPS" version="1.0.0" xml:lang="en-CA"> <ProcessDescription wps:processVersion="1" storeSupported="false" statusSupported="false"> <ows:Identifier>constituents</ows:Identifier> <ows:Title>Lookup constituents based on their short name</ows:Title> <ows:Abstract> Lookup the speed of the constiuent based on the name of the constituent (following Doodson). </ows:Abstract> <DataInputs> <Input minOccurs="1" maxOccurs="1"> <ows:Identifier>date</ows:Identifier> <ows:Title>Date for which to calculate the nodal factors</ows:Title> <LiteralData> <ows:DataType ows:reference="http://www.w3.org/TR/xmlschema-2/#string">string</ows:DataType> <ows:AnyValue/> <DefaultValue/> </LiteralData> </Input> <Input minOccurs="1" maxOccurs="1"> <ows:Identifier>constituent</ows:Identifier> <ows:Title>Name of the constituent to look up (M2,...)</ows:Title> <LiteralData> <ows:DataType ows:reference="http://www.w3.org/TR/xmlschema-2/#string">string</ows:DataType> <ows:AnyValue/> </LiteralData> </Input> <Input minOccurs="1" maxOccurs="1"> <ows:Identifier>nodal</ows:Identifier> <ows:Title>Calculate nodal factors</ows:Title> <LiteralData> <ows:DataType ows:reference="http://www.w3.org/TR/xmlschema-2/#boolean">boolean</ows:DataType> <ows:AnyValue/> <DefaultValue>False</DefaultValue> </LiteralData> </Input> </DataInputs> <ProcessOutputs> <Output> <ows:Identifier>u</ows:Identifier> <ows:Title>u taken from Schureman</ows:Title> <LiteralOutput> <ows:DataType ows:reference="http://www.w3.org/TR/xmlschema-2/#float">float</ows:DataType> </LiteralOutput> </Output> <Output> <ows:Identifier>speed</ows:Identifier> <ows:Title>Speed of the constituent (radians per hour)</ows:Title> ... </Output> <Output> <ows:Identifier>FF</ows:Identifier> <ows:Title>FF nodal factor, taken from Schureman</ows:Title> <LiteralOutput> <ows:DataType ows:reference="http://www.w3.org/TR/xmlschema-2/#float">float</ows:DataType> </LiteralOutput> </Output> <Output> <ows:Identifier>VAU</ows:Identifier> <ows:Title>V+u taken from Schureman</ows:Title> <LiteralOutput> <ows:DataType ows:reference="http://www.w3.org/TR/xmlschema-2/#float">float</ows:DataType> </LiteralOutput> </Output> </ProcessOutputs> </ProcessDescription> </wps:ProcessDescriptions>
In the DescribeProcess document all information about the specific process is given. In the document general information is given in a title and abstract. Besides these also different in- and outputs are defined including titles, datatypes, default values, etc. In the document above we find three different inputs and four different outputs.
Execute a specific process of the WPS server
After finding out the required input parameters for the specific process, the Execute request can be send.
keyword |
value |
source |
---|---|---|
service |
WPS |
Mandatory WPS standard value |
version |
1.0.0 |
Mandatory for Execute |
request |
Execute |
Mandatory WPS standard value |
identifer |
process name |
Mandatory parameter |
DataInputs |
inpute parameters |
Mandatory for Execute |
language |
Usually 'en' (English) |
Optional |
Since processes can contain multiple inputs, the DataInputs parameter looks somewhat different. The shape of this parameter is shown below. The different parameters are all after the equal sign (=) of datainputs and between brackets. The different parameters are separated by semicolons (;). Which input parameters are required and how these can be used is found in the DescribeProcess document, at the <ows:identifier> tag the identifier of the input parameter is given, this identifier is used in the URL.
datainputs=[parameter_1=5;parameter_2=9;parameter_3=false]
For the purpose of this example only a single input value will be used in the execute request below.
http://dtvirt5.deltares.nl/wps/? request=Execute& service=wps& version=1.0.0& identifier=constituents& datainputs=[constituent=M2]
The result of the Execute request is an XML document containing the different output parameters with corresponding output values.
<wps:ExecuteResponse xmlns:wps="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 http://schemas.opengis.net/wps/1.0.0/wpsExecute_response.xsd" service="WPS" version="1.0.0" xml:lang="en-CA" serviceInstance="http://dtvirt5.deltares.nl/wps?service=WPS&request=GetCapabilities&version=1.0.0" statusLocation="http://dtvirt5.deltares.nl/outputwps/pywps-137639971224.xml"> <wps:Process wps:processVersion="1"> <ows:Identifier>constituents</ows:Identifier> <ows:Title>Lookup constituents based on their short name</ows:Title> <ows:Abstract>...</ows:Abstract> </wps:Process> <wps:Status creationTime="2013-08-13T15:15:12Z"> <wps:ProcessSucceeded>PyWPS Process constituents successfully calculated</wps:ProcessSucceeded> </wps:Status> <wps:ProcessOutputs> <wps:Output> <ows:Identifier>u</ows:Identifier> <ows:Title>u taken from Schureman</ows:Title> <wps:Data> <wps:LiteralData dataType="float" uom="None">12.5910330876</wps:LiteralData> </wps:Data> </wps:Output> <wps:Output> <ows:Identifier>speed</ows:Identifier> <ows:Title>Speed of the constituent (radians per hour)</ows:Title> <wps:Data> <wps:LiteralData dataType="float" uom="r">0.505868049939</wps:LiteralData> </wps:Data> </wps:Output> <wps:Output> <ows:Identifier>FF</ows:Identifier> <ows:Title>FF nodal factor, taken from Schureman</ows:Title> <wps:Data> <wps:LiteralData dataType="float" uom="None">1.0281626242</wps:LiteralData> </wps:Data> </wps:Output> <wps:Output> <ows:Identifier>VAU</ows:Identifier> <ows:Title>V+u taken from Schureman</ows:Title> <wps:Data> <wps:LiteralData dataType="float" uom="None">16.2091031443</wps:LiteralData> </wps:Data> </wps:Output> </wps:ProcessOutputs> </wps:ExecuteResponse>