Processes

specdraftimplproposal

Retrieve descriptions of supported processes and execute them.

Scope

Processes allows describing, retrieving and executing processes.

Process descriptions are defined using the requirements class OGC PROCESS DESCRIPTION. They can be defined globally and on a per-API basis.

This building block supports both synchronous and asynchronous execution of processes. Using the configuration, it is possible to limit support to only synchronous or asynchronous execution, or to support both modes.

Important: The async endpoints (/jobs/...) are enabled through the helper building block Async, which is activated automatically. Read its documentation for further information about the asynchronous endpoints.

Some limitations apply; see the Limitations section.

Limitations

This implementation does not cover all details and has some limitations:

• All inputs must be provided inline. References are not supported.
• Inputs and outputs cannot have multiple schemas.
• From the JSON Schema Validation formats, only date-time is supported.
• From the additional OGC PROCESS DESCRIPTION formats, only ogc-bbox is supported.
• mediatype, encoding and schema are not honored in output selection.
• Binary values are not supported.
• null is not supported as an input value.
• Requirement 50 ("0-th" result) is not supported.
• Input descriptions do not support Data classes, Data access APIs or Execution unit requirements.
• Output descriptions do not support Data classes or Data access APIs.
• The behavior of the dismiss endpoint intentionally differs from the draft: instead of removing the job when its state is successful, failed or dismissed, nothing is changed.

As this API has not been thoroughly tested yet, there is a chance that it may include other limitations and/or undesired behavior.

Conformance Classes

The building block is based on the specifications of the conformance classes "Core", "OGC Process Description", "JSON", "HTML", "OpenAPI Specification 3.0", "Callback" and "Dismiss" from the Draft OGC API - Processes - Part 1: Core. The implementation will change as the draft evolves during the standardization process.

Operations

Resource	Path	Methods	Media Types	Description
Process List	processes	GET	HTML, JSON	Returns a list containing the summaries of a subset of all processes supported by this API. Supports pagination using links (first, next, prev and last) to discover all subsets.
Process details	processes/{processId}	GET	HTML, JSON	Returns the complete details of a process.
Execute	processes/{processId}/execution	POST	Any, HTML, JSON	Triggers the execution of a process. The inputs, output selection and possible callback subscribers are sent in the request body. If the process is executed synchronously, the results are computed and returned directly, otherwise the status info of the corresponding job is returned.

Path Parameters

Name	Resources	Description
processId	processes/{processId}, processes/{processId}/execution	The local identifier of a process, unique within the API.

Query Parameters

Name	Resources	Description
limit	processes	The maximum number of process summaries that are presented in the response document. If more process summaries are available, a link to the next page is provided with the response. If no parameter value is provided, the default value that is configured for the API applies.
offset	processes	The index of the first process summary in the overall result set to include in the response. This parameter is used for paging.
f	processes/{processId}	Select the output format of the response. If no value is provided, the standard HTTP rules apply, i.e., the "Accept" header will be used to determine the format.
f	processes	Select the output format of the response. If no value is provided, the standard HTTP rules apply, i.e., the "Accept" header will be used to determine the format.
f	processes/{processId}/execution	Select the output format of the response. If no value is provided, the standard HTTP rules apply, i.e., the "Accept" header will be used to determine the format.

Configuration

Options

Name	Default	Description	Type	Since
buildingBlock		Always PROCESSES_CORE.	string	v2.0
async	false	Enables asynchronous execution. A request with Prefer: respond-async is accepted with status 202 and executed as a background job; progress and outcome are tracked by the job. When disabled, requests with respond-async are executed synchronously.	boolean	v4.9
maxWait	60	Only relevant when async is enabled. Upper bound in seconds for the wait preference: a request with Prefer: respond-async, wait=n is executed as a background job, but the response is deferred for up to min(n, maxWait) seconds \u2014 if the job finishes in time, the regular synchronous response is returned and the stored result is deleted, otherwise the request is answered with status 202 and the job continues.	number	v4.9
jobTtl	1h	Only relevant when async is enabled. Time-to-live for a job: after the job has finished, its status and results are kept for up to jobTtl, after which they are deleted. A job is finished when it was either cancelled/dismissed, failed or completed. This is a soft limit, the actual deletion may be delayed.	string	v4.9
enabled	false	Enable the building block?	boolean	4.9
defaultPageSize	10	Sets the default value for parameter limit.	number	4.9
minimumPageSize	1	Sets the minimum value for parameter limit.	number	4.9
maximumPageSize	10000	Sets the maximum value for parameter limit.	number	4.9
callbackRetries	3	Indicates how often the callback should be retried at most, when the subscriber cannot be reached or responds with a server error (5xx), 408 or 429. A client may request fewer retries with maxRetries in the subscriber of the execute request. Should be set to 0 if no retries are desired.	number	4.9
allowedCallbackUris	[]	The URIs to which the callbacks of an asynchronous execution may be sent. A callback URI of a subscriber is accepted, if it has the scheme, host and port of an entry and its path starts with the path of the entry, e.g. https://example.com/callbacks/ accepts https://example.com/callbacks/job-done. The entry * accepts every HTTP(S) URI; use it only for tests or in a closed environment, since a client can then direct requests of the server to any host the server can reach, including services that are only reachable from the server. Without an entry, callbacks are not supported and an asynchronous execution with a subscriber is rejected.	array	4.9
syncTimeout	5m	Maximum duration of a synchronous process execution. If the process has not finished by then, the job is cancelled and the request fails with status code 504.	string	4.9

Storage

Process descriptions are stored locally as values using the Store. Global process descriptions are stored in values/processes. API-specific process descriptions must be stored in values/processes/{apiId}, where {apiId} is the id of the API.

For the structure of process descriptions and the options of the job that runs an execution, see Processes.

Examples

Example config for an API:

- buildingBlock: PROCESSES_CORE
   enabled: true
   defaultPageSize: 10
   minimumPageSize: 5
   maximumPageSize: 100
   callbackRetries: 2
   allowedCallbackUris:
     - https://example.com/callbacks/
   async: true
 

Example for the process description of a simple Echo-Process:

 id: "EchoProcess"
title: "Echo Process"
description: "This process simply echoes its input as an output."
version: "1.0.0"
jobControlOptions: [ SYNC_EXECUTE, ASYNC_EXECUTE ]
outputs:
 inputString:
   title: "Input String"
   description: "The echoed single string value."
   valuePassing: [ BY_VALUE ]
   schema:
     type: string
   maxOccurs: 1
   minOccurs: 0
inputs:
 inputString:
   title: "Input String"
   description: "A single string value to echo."
   valuePassing: [ BY_VALUE ]
   schema:
     type: string
   maxOccurs: 1
   minOccurs: 0
 

If the process is meant to be global, this must be stored in values/processes. If the process is for a specific API foo, it must be in values/processes/foo.

For more information on how to describe a process, see OGC PROCESS DESCRIPTION.