The Execute operation allows WPS clients to run a specified process implemented by a server, using the input parameter values provided and returning the output values produced. Inputs can be included directly in the Execute request, or reference web accessible resources.

Execute Request

The operation request provides support for multiple inputs. Each input refers to one of the forms of input that may be required for a single Execute request. The normal way to provide large inputs to a WPS is through providing one or more URIs (usually URLs) of input values, unless the inputs are simple scalar values. This is not intended to be used to facilitate batch processing (e.g., multiple images to be processed through a single algorithm). If a process is to be run multiple times (probably using different inputs each time), each run shall be submitted as a separate Execute operation request.

Note that the list of process inputs and outputs is unsorted. This means that when large numbers of inputs or outputs exist for a process, an excessive overhead may be placed on server and client portal interface software as it attempts to interpret the incoming data stream and transform it as required. For such cases, the implementer is advised to package and sort the inputs / outputs in an efficient manner, and identify this optimal sorting requirement in the process description

WPS offers three different methods for invoking an Execute request, as detailed below.

HTTP GET method using KVP (optional)

Servers may implement an Execute request via HTTP GET, using KVP to encode the parameters. KVP encoding is suitable for simple Execute requests. More complex requests such as those which require the inclusion of embedded complex values should use the XML encoding.

HTTP POST method using XML (mandatory)

WPS servers shall implement Execute request via HTTP POST. The request parameters are encoded as XML elements, with their contents identical to those indicated in the parameter table shown above according to the Execute request XML schema.

SOAP (optional)

SOAP-encoded requests and responses use SOAP document-style encoding (also called message-style or document-literal encoding), as described in [OWS 06-094]. WPS SOAP messages simply contain a normal XML-encoded request or response wrapped in a SOAP envelope.

Execute Response

The form of the response to an Execute operation request depends on the value of the "ResponseForm" parameter in the execute request.

In the special case of a single output, a WPS server can be directed to return that output in its raw form. This form of response is known as RawDataOutput.

In all other cases, the normal response to an execute request is a Response Document. This document is encoded in XML. Outputs produced by a process may either be embedded within the Response Document or stored as web accessible resources. If the outputs are stored, the Response Document will include a URL for each stored output, which the client can use to retrieve those outputs.

In the special case of a Response Document for a long-running process, a WPS server can be directed to store the Response Document at a URL and update the contents of that URL as processing occurs.

These different modes of responses are described in more detail below.

Raw Data Output

In the most primitive case, when:

  1. a response form of "RawDataOutput" is requested,
  2. process execution is successful, and
  3. only one complex output is produced,

then the Execute operation response will consist simply of that one complex output in its raw form returned directly to the client.

For example, if the WPS process created one GIF image as its output, that GIF image would be returned to the client as the response to the Execute request.

Raw data output is requested by including "RawDataOutput=true" as part of an Execute via HTTP GET request, or by including the RawDataOutput element within the ResponseForm element of the Execute via HTTP POST request.

Response Document

Normally, the response to an Execute request is a Response Document that is returned to the client after process execution is completed. The contents of this ExecuteResponse document depend upon the value of the Execute/ResponseForm/ResponseDocument element, as follows.

If storeExecuteResponse is "true", then the execute response document shall be stored at a web accessible URL. The statusLocation attribute in the execute response becomes mandatory, which will point to the location where the Response Document is stored. The service shall respond immediately to the request by

  • storing the Response Document at a web accessible URL, as well as
  • returning the Response Document containing the statusLocation to the client.

The status element which has five possible subelements: ProcessAccepted, ProcessStarted, ProcessPaused, ProcessFailed and ProcessSucceeded> These elements are chosen and populated as follows:

  1. If the process is completed when the initial Response Document is returned, the element ProcessSucceeded is populated with the process results.
  2. If the process already failed when the initial Response Document is returned, the element ProcessFailed is populated with the Exception.
  3. If the process has been paused when the initial Response Document is returned, the element ProcessPaused is populated.
  4. If the process has been accepted when the initial Response Document is returned, the element ProcessAccepted is populated, including percentage information.
  5. If the process execution is ongoing when the initial Response Document is returned, the element ProcessStarted is populated.

In case 3, 4, and 5, if status updating is requested, updates are made to the Response Document at the statusLocation until either the process completes successfully or it fails. Regardless, once the process completes successfully, the ProcessSucceeded element is populated, and if it fails, the ProcessFailed element is populated.

If lineage is "true", the Execute operation response shall include the DataInputs and OutputDefinitions elements. The server shall include in the execute response a complete copy of the DataInputs and OutputDefinition elements as received in the execute request. If lineage is "false" then these elements shall be omitted from the response.

If status is "true", the stored execute response document shall be updated to provide ongoing reports on the status of execution. If status is "true" and storeExecuteResponse is "true" (and the server has indicated that both storeSupported and statusSupported are "true") then the Status element of the execute response document stored at statusLocation is kept up to date by the process. While the execute response contains ProcessAccepted, ProcessStarted, or ProcessPaused, updates shall be made to the executeResponse document until either the process completes successfully (in which case ProcessSucceeded is populated), or the process fails (in which case ProcessFailed is populated). If status is "false" then the Status element shall not be updated until the process either completes successfully or fails. If status="true" and storeExecuteResponse is "false" then the service shall raise an exception.

If storage of a ComplexData output has not been requested via the "asReference" attribute, the ExecuteResponse document will contain that output. For ComplexData such as images included in the ExecuteResponse document will be encoded. If storage of a ComplexData output is requested, the ExecuteResponse will reference the web-accessible resource where the output can be retrieved.

Response Document Schema

An Execute Response Document is encoded in XML according to the Execute response XML schema.

Examples

Response Document for a Long-Running Process

Response Documents for long running processes extend the content of a normal Response Document. For long-running processes, client can instruct the server to return the Execute response document immediately following acceptance by the server of the Execute request. In this case, the Execute response includes a URL from which an updated response document can be retrieved during and after process execution.

Requesting ongoing updates to process status

By default, the server will wait to update the stored Response Document until processing is complete. However, the server can be instructed to provide regular updates to a measure of the amount of processing remaining while the process is incomplete. This allows the client to determine the process status by polling this URL. A typical example of how this works is shown in the UML activity diagram below.

Exceptions

When a WPS server encounters an error while performing an Execute operation, it shall return an exception report message as specified in Clause 8 of [OGC 06-121r3]. The allowed exception codes shall include those listed in Table 5 of Subclause 7.4.1 of [OGC 06-121r3].

Examples

For more information on structuring requests, please see the WPS Standard.

This site is sponsored by

Ruby Informatics Corporation