From ae91de243ff48317a6cb2f659b87b1dcca794fc4 Mon Sep 17 00:00:00 2001 From: Francis Charette Migneault Date: Sat, 18 Jul 2026 03:00:58 -0400 Subject: [PATCH 1/3] proposal functional CWL ad-hoc execution with multipart --- core/sections/annex-history.adoc | 2 +- .../standard/20-044.adoc | 2 +- .../standard/sections/clause_7_apppkg.adoc | 4 +- .../standard/sections/clause_9_cwl.adoc | 4 +- extensions/workflows/21-009.adoc | 1 + .../PER_cwl-workflows_adhoc-cwl-deploy.adoc | 35 +++ ...dhoc-cwl-multipart-alternate-encoding.adoc | 35 +++ ...l-workflows_adhoc-cwl-multipart-files.adoc | 27 +++ ...REQ_cwl-workflows_adhoc-cwl-execution.adoc | 9 - ...cwl-workflows_adhoc-cwl-job-execution.adoc | 38 +++ ...workflows_adhoc-cwl-multipart-content.adoc | 59 +++++ ...workflows_adhoc-cwl-process-execution.adoc | 41 ++++ .../requirements_class_cwl-workflows.adoc | 4 +- .../workflows/sections/annex-history.adoc | 1 + .../sections/clause_0_front_material.adoc | 2 +- .../sections/clause_12_cwl_workflows.adoc | 223 +++++++++++++++++- .../sections/clause_3_references.adoc | 10 +- 17 files changed, 465 insertions(+), 32 deletions(-) create mode 100644 extensions/workflows/recommendations/cwl-workflows/PER_cwl-workflows_adhoc-cwl-deploy.adoc create mode 100644 extensions/workflows/recommendations/cwl-workflows/PER_cwl-workflows_adhoc-cwl-multipart-alternate-encoding.adoc create mode 100644 extensions/workflows/recommendations/cwl-workflows/REC_cwl-workflows_adhoc-cwl-multipart-files.adoc delete mode 100644 extensions/workflows/requirements/cwl-workflows/REQ_cwl-workflows_adhoc-cwl-execution.adoc create mode 100644 extensions/workflows/requirements/cwl-workflows/REQ_cwl-workflows_adhoc-cwl-job-execution.adoc create mode 100644 extensions/workflows/requirements/cwl-workflows/REQ_cwl-workflows_adhoc-cwl-multipart-content.adoc create mode 100644 extensions/workflows/requirements/cwl-workflows/REQ_cwl-workflows_adhoc-cwl-process-execution.adoc diff --git a/core/sections/annex-history.adoc b/core/sections/annex-history.adoc index 8265b14f..251d19c7 100644 --- a/core/sections/annex-history.adoc +++ b/core/sections/annex-history.adoc @@ -27,7 +27,7 @@ |2019-10-01 |1.0-draft.3 |Benjamin Pross| 7 |1.0-draft.3, minor edits |2019-10-10 |1.0-draft.3 |Gérald Fenoy, Tom Kralidis| 7 |Add implementations, Use status in place of infos in jobInfo definition |2019-10-22 |1.0-draft.3 |Benjamin Pross| 7 |Remove mandatory path /api, fix for #50 -|2020-01-06 |1.0-draft.3 |Francis Charette| 7 |Add implementation +|2020-01-06 |1.0-draft.3 |Francis Charette-Migneault| 7 |Add implementation |2020-01-28 |1.0-draft.3 |Gérald Fenoy| 7 |Adjust schemas and examples |2020-02-03 |1.0-draft.3 |Benjamin Pross| 7 |Fix for #63 |2020-02-18 |1.0-draft.3 |Chris Durbin| 7 |Fix for #61 diff --git a/extensions/deploy_replace_undeploy/standard/20-044.adoc b/extensions/deploy_replace_undeploy/standard/20-044.adoc index 77857154..7750c6db 100644 --- a/extensions/deploy_replace_undeploy/standard/20-044.adoc +++ b/extensions/deploy_replace_undeploy/standard/20-044.adoc @@ -12,7 +12,7 @@ :external-id: https://www.opengis.net/doc/IS/ogcapi-processes-2/1.0 :keywords: process, collection, instance, spatial, data, openapi, transactions, insert, update, delete, add, remove, deploy, undeploy, REST, PUT, POST, DELETE :submitting-organizations: Geolabs; CubeWerx Inc; Terradue Srl.; Wuhan University (WHU); Technologies Luqia, Centre de Recherche Informatique de Montréal (CRIM) -:editor: Panagiotis (Peter) A. Vretanos, Gérald Fenoy +:editor: Panagiotis (Peter) A. Vretanos, Gérald Fenoy, Francis Charette-Migneault :mn-document-class: ogc :mn-output-extensions: xml,html,doc,pdf :htmltoclevels: 4 diff --git a/extensions/deploy_replace_undeploy/standard/sections/clause_7_apppkg.adoc b/extensions/deploy_replace_undeploy/standard/sections/clause_7_apppkg.adoc index 481a39c0..705e8365 100644 --- a/extensions/deploy_replace_undeploy/standard/sections/clause_7_apppkg.adoc +++ b/extensions/deploy_replace_undeploy/standard/sections/clause_7_apppkg.adoc @@ -60,13 +60,13 @@ The following example illustrates an execution unit where the executable code is "value": { "image": "mydocker/ndvi:latest", "bindings": { - "inputBindings": { + "inputBinding": { "inputImage": { "prefix": "inputsImages=", "inputSeparator": "," } }, - "outputBindings": { + "outputBinding": { "outputImage": { "glob": "$(\"/outputs/ndvi_\" + inputs.inputImage.basename)" } diff --git a/extensions/deploy_replace_undeploy/standard/sections/clause_9_cwl.adoc b/extensions/deploy_replace_undeploy/standard/sections/clause_9_cwl.adoc index 9e2d88ca..845f0c71 100644 --- a/extensions/deploy_replace_undeploy/standard/sections/clause_9_cwl.adoc +++ b/extensions/deploy_replace_undeploy/standard/sections/clause_9_cwl.adoc @@ -76,7 +76,7 @@ Below are other examples of <> bodies where the CWL value ==== Overview -This clause defines the requirements for sending a CWL document directly to the process deployment endpoint (i.e. /processes) without embedding the CWL into an <> +This clause defines the requirements for sending a CWL document directly to the process deployment endpoint (i.e. `/processes`) without embedding the CWL into an <> ==== CWL request body @@ -84,7 +84,7 @@ include::../requirements/cwl/REQ_body.adoc[] ==== Multipart CWL request body -include::../recommendations/cwl/REC_body-cwl-multipart.adoc[] +include::../recommendations/cwl/PER_body-cwl-multipart.adoc[] The following multipart example illustrates one request payload with a root workflow selected by the `start` parameter, with supporting documents referenced by `filename`, `cid:` URI and remote URL combinations. The full contents of the individual <> documents are not included for simplification. Note that the <> YAML representation are employed to provide a concise example, but other <> media-types are permitted in any desired combination. diff --git a/extensions/workflows/21-009.adoc b/extensions/workflows/21-009.adoc index a4078e85..8197544f 100644 --- a/extensions/workflows/21-009.adoc +++ b/extensions/workflows/21-009.adoc @@ -12,6 +12,7 @@ :published-date: 2029-03-30 :fullname: Jérôme Jacovella-St-Louis :fullname_2: Panagiotis (Peter) A. Vretanos +:fullname_3: Francis Charette-Migneault :docsubtype: implementation :keywords: ogcdoc, OGC document, API, openapi, html, ogcapi :submitting-organizations: Ecere Corporation; CubeWerx Inc.; GeoLabs; University of Calgary; Pangaea Innovations Pty. Ltd.; Natural Resources Canada; EOX IT Services GmbH; Universitat Autònoma de Barcelona (CREAF); Technologies Luqia, Centre de Recherche Informatique de Montréal (CRIM); 52°North Spatial Information Research GmbH; European Space Agency (ESA); US Army Geospatial Center (AGC); Hexagon; Haute École d'Ingénierie et de Gestion du Canton de Vaud (HEIG-VD); Laboratoire des Sciences et Techniques de l'information de la Communication et de la Connaissance / Centre national de la recherche scientifique (Lab-STICC CNRS) diff --git a/extensions/workflows/recommendations/cwl-workflows/PER_cwl-workflows_adhoc-cwl-deploy.adoc b/extensions/workflows/recommendations/cwl-workflows/PER_cwl-workflows_adhoc-cwl-deploy.adoc new file mode 100644 index 00000000..cd82d9d8 --- /dev/null +++ b/extensions/workflows/recommendations/cwl-workflows/PER_cwl-workflows_adhoc-cwl-deploy.adoc @@ -0,0 +1,35 @@ +[[per_cwl-workflows_adhoc-cwl-deploy]] +[permission] +==== +[%metadata] +identifier:: /per/cwl-workflows/adhoc-cwl-deploy +description:: Capability for a server to deploy and/or undeploy the CWL resulting from ad-hoc execution request. + +[.component,class=conditions] +-- +. The server declares conformance to <>. +. The submitted job defines an ad-hoc CWL definition along the execution request. +-- + +[.component,class=part] +-- +The server MAY deploy the CWL as an intermediate operation of the ad-hoc execution. +-- + +[.component,class=part] +-- +The server MAY decide to reuse a predeployed CWL that matches the provided ad-hoc definition. +-- + +[.component,class=part] +-- +If a deployment resulted from the job submission, the server MAY undeploy the ad-hoc CWL definition following execution completion. +-- + +[.component,class=part] +-- +The server MAY preserve (i.e.: not undeploy) the ad-hoc CWL definition following execution completion +if it deems it necessary for reuse, reporting and traceability requirements. +-- + +==== diff --git a/extensions/workflows/recommendations/cwl-workflows/PER_cwl-workflows_adhoc-cwl-multipart-alternate-encoding.adoc b/extensions/workflows/recommendations/cwl-workflows/PER_cwl-workflows_adhoc-cwl-multipart-alternate-encoding.adoc new file mode 100644 index 00000000..2a38c839 --- /dev/null +++ b/extensions/workflows/recommendations/cwl-workflows/PER_cwl-workflows_adhoc-cwl-multipart-alternate-encoding.adoc @@ -0,0 +1,35 @@ +[[per_cwl-workflows_adhoc-cwl-multipart-alternate-encoding]] +[permission] +==== +[%metadata] +identifier:: /per/cwl-workflows/adhoc-cwl-multipart-alternate-encoding +description:: Allow using alternate presentations of equivalent contents. + +[.component,class=part] +-- +For each part of the <> +multipart request, the server MAY support alternate presentations of equivalent contents (e.g.: YAML instead of JSON). +-- + +[.component,class=part] +-- +The corresponding part SHOULD report the corresponding `Content-Type` best representing the encoding +(e.g., `application/cwl+yaml` instead of `application/yaml` if the part represents CWL). +-- + +[.component,class=part] +-- +The server SHOULD rely on other profiling details (i.e.: `Content-Profile` to identify parts regardless of encoding. +-- + +[.component,class=part] +-- +The server MAY apply other heuristics to identify alternate representations of equivalent contents, +such as file extension, or other metadata. +-- + +==== + +NOTE: This standard does not specify any explicit strategy to convert between alternate media-type representations. +However, it is expected that if such permission is employed, equivalent interpretation of corresponding part contents +can be achieved unambiguously. diff --git a/extensions/workflows/recommendations/cwl-workflows/REC_cwl-workflows_adhoc-cwl-multipart-files.adoc b/extensions/workflows/recommendations/cwl-workflows/REC_cwl-workflows_adhoc-cwl-multipart-files.adoc new file mode 100644 index 00000000..4ea2724d --- /dev/null +++ b/extensions/workflows/recommendations/cwl-workflows/REC_cwl-workflows_adhoc-cwl-multipart-files.adoc @@ -0,0 +1,27 @@ +[[rec_cwl-workflows_adhoc-cwl-multipart-files]] +[recommendation] +==== +[%metadata] +identifier:: /rec/cwl-workflows/adhoc-cwl-multipart-files +description:: Capability to provide additional files required for execution of the ad-hoc CWL workflow. + +[.component,class=part] +-- +If the execution of the ad-hoc CWL requires additional data files to be provided, +they MAY be supplied with additional multipart parts. +-- + +[.component,class=part] +-- +Additional files encoded within multipart parts SHOULD leverage +the `Content-Disposition: filename=""` header to indicate how part contents might be referenced. +-- + +[.component,class=part] +-- +The CWL ad-hoc execution SHOULD reuse the provided file name in the part to bind it with +link:https://www.commonwl.org/v1.2/CommandLineTool.html#File[CWL File] supported mechanisms +to collect this file during execution (e.g., `glob`, `path`, `location`, etc.). +-- + +==== diff --git a/extensions/workflows/requirements/cwl-workflows/REQ_cwl-workflows_adhoc-cwl-execution.adoc b/extensions/workflows/requirements/cwl-workflows/REQ_cwl-workflows_adhoc-cwl-execution.adoc deleted file mode 100644 index 843ded12..00000000 --- a/extensions/workflows/requirements/cwl-workflows/REQ_cwl-workflows_adhoc-cwl-execution.adoc +++ /dev/null @@ -1,9 +0,0 @@ -[requirement] -==== -[%metadata] -identifier:: /req/cwl-workflows/adhoc-cwl-execution -description:: For executing a workflow defined using the Common Workflow Language (CWL) definition: -part:: The Implementation SHALL support ad-hoc execution of a CWL workflow definition (`Content-Type: application/cwl+json`) POSTed to `/processes/CWL/execution`. -==== - -TODO: Verify whether a `{processID}` for the execution end-point is relevant or not for CWL. diff --git a/extensions/workflows/requirements/cwl-workflows/REQ_cwl-workflows_adhoc-cwl-job-execution.adoc b/extensions/workflows/requirements/cwl-workflows/REQ_cwl-workflows_adhoc-cwl-job-execution.adoc new file mode 100644 index 00000000..797b6edc --- /dev/null +++ b/extensions/workflows/requirements/cwl-workflows/REQ_cwl-workflows_adhoc-cwl-job-execution.adoc @@ -0,0 +1,38 @@ +[[REQ_cwl-workflows_adhoc-cwl-job-execution]] +[requirement] +==== +[%metadata] +identifier:: /req/cwl-workflows/adhoc-cwl-job-execution +inherit:: <> +description:: For executing a workflow defined using the Common Workflow Language (CWL) definition, through _Job Management_ execution. + +[.component,class=part] +-- +The server SHALL support ad-hoc execution of a CWL workflow definition on `POST /jobs` endpoint. +-- + +[.component,class=part] +-- +The execution and response handling SHALL behave according to other execution parametrization (`Prefer` header, etc.) +defined by <>. +-- + +[.component,class=part] +-- +The request SHALL employ the `Content-Type: multipart/related` media type as defined in <> to submit the +CWL definition and its associated execution parameters. +-- + +[.component,class=part] +-- +The multipart contents SHALL follow <> +for the definition of part contents. +-- + +[.component,class=part] +-- +The `inputs` and `outputs` IDs of the execution body SHALL be aligned with the CWL definition IDs of respective sections +to allow chaining their respective values and results. +-- + +==== diff --git a/extensions/workflows/requirements/cwl-workflows/REQ_cwl-workflows_adhoc-cwl-multipart-content.adoc b/extensions/workflows/requirements/cwl-workflows/REQ_cwl-workflows_adhoc-cwl-multipart-content.adoc new file mode 100644 index 00000000..d3c65c0b --- /dev/null +++ b/extensions/workflows/requirements/cwl-workflows/REQ_cwl-workflows_adhoc-cwl-multipart-content.adoc @@ -0,0 +1,59 @@ +[[REQ_cwl-workflows_adhoc-cwl-multipart-content]] +[requirement] +==== +[%metadata] +identifier:: /req/cwl-workflows/adhoc-cwl-multipart-content +inherit:: <> +description:: Multipart content to combine Common Workflow Language (CWL) definition and execution parameters. + +[.component,class=part] +-- +The request SHALL employ the `Content-Type: multipart/related` media type as defined in <> to submit the +CWL definition and its associated execution parameters. +-- + +[.component,class=part] +-- +At least one part corresponding to CWL contents SHALL be provided. +-- + +[.component,class=part] +-- +The media-type of each individual CWL part in the multipart body SHALL be specified by their respective +part `Content-Type` header using `application/cwl`, `application/cwl+json` or `application/cwl+yaml` media-types +in accordance to their respective content encoding. +-- + +[.component,class=part] +-- +If the CWL definition contains multiple workflow steps defined across multiple parts +(e.g: as if providing multiple files where each part implements part of the workflow), +the multipart `Content-Type` SHALL provide a `start=` parameter (as per <>) +referring to the `Content-ID` value of the corresponding part that represents this workflow "root" as the +entrypoint part for execution. +-- + +[.component,class=part] +-- +The header portion of the part corresponding to +the <> +SHALL contain: + +. the `+Content-Profile: +` profile header +to indicate the semantics of the part. +. the `Content-Type: application/json` header to indicate its encoding. +-- + +[.component,class=part] +-- +Exactly one part corresponding to the execution content (`inputs`, `outputs`, etc.) SHALL be provided and respect the +https://raw.githubusercontent.com/opengeospatial/ogcapi-processes/master/openapi/schemas/processes-core/execute.yaml[execute.yaml] schema. +-- + +[.component,class=part] +-- +If a part employs a `Content-Location` header, it contents SHALL be retrieved from the provided URL, +unless the literal data contents are also provided explicitly within the part. +-- + +==== diff --git a/extensions/workflows/requirements/cwl-workflows/REQ_cwl-workflows_adhoc-cwl-process-execution.adoc b/extensions/workflows/requirements/cwl-workflows/REQ_cwl-workflows_adhoc-cwl-process-execution.adoc new file mode 100644 index 00000000..ed9991db --- /dev/null +++ b/extensions/workflows/requirements/cwl-workflows/REQ_cwl-workflows_adhoc-cwl-process-execution.adoc @@ -0,0 +1,41 @@ +[[REQ_cwl-workflows_adhoc-cwl-process-execution]] +[requirement] +==== +[%metadata] +identifier:: /req/cwl-workflows/adhoc-cwl-process-execution +inherit:: <> +inherit:: <> +description:: For executing a workflow defined using the Common Workflow Language (CWL) definition, through _Core_ nested process execution. + +[.component,class=part] +-- +The server SHALL support ad-hoc execution of a CWL workflow definition on `POST /processes/{processId}/execution` endpoint. +-- + +[.component,class=part] +-- +The execution and response handling SHALL behave according to other execution parametrization (`Prefer` header, etc.) +defined by <>. +-- + +[.component,class=part] +-- +The request SHALL employ the `Content-Type: multipart/related` media type as defined in <> to submit the +CWL definition and its associated execution parameters. +-- + +[.component,class=part] +-- +The multipart contents SHALL follow <> +for the definition of part contents. +-- + +[.component,class=part] +-- +The part containing the <> +SHALL provide in the `"inputs"` any necessary mapping to a `+{"$output": ""}+` where the `++` +indicates the output identifier from the main CWL workflow from which the resulting value SHALL be chained from +the CWL execution into the corresponding input of the parent `{processId}`. +-- + +==== diff --git a/extensions/workflows/requirements/requirements_class_cwl-workflows.adoc b/extensions/workflows/requirements/requirements_class_cwl-workflows.adoc index 70e3c496..a1c01b72 100644 --- a/extensions/workflows/requirements/requirements_class_cwl-workflows.adoc +++ b/extensions/workflows/requirements/requirements_class_cwl-workflows.adoc @@ -4,6 +4,8 @@ [%metadata] identifier:: http://www.opengis.net/spec/ogcapi-processes-3/0.0/req/cwl-workflows subject:: Common Workflow Language Definitions -inherit:: http://www.opengis.net/spec/ogcapi-processes-1/1.0/req/core inherit:: Common Workflow Language <> +requirement:: /req/cwl-workflows/adhoc-cwl-process-execution +requirement:: /req/cwl-workflows/adhoc-cwl-job-execution +requirement:: /req/cwl-workflows/adhoc-cwl-multipart-content ==== diff --git a/extensions/workflows/sections/annex-history.adoc b/extensions/workflows/sections/annex-history.adoc index e4f7ba20..baddac0c 100644 --- a/extensions/workflows/sections/annex-history.adoc +++ b/extensions/workflows/sections/annex-history.adoc @@ -7,4 +7,5 @@ |Date |Release |Editor | Primary clauses modified |Description |2020-10-19 |0.1 |J. St-Louis |all |initial draft |2022-10-19 |0.2 |J. St-Louis |all |reorganized into multiple conformance classes, using metanorma template, with more detailed descriptions and requirements +|2026-07-18 |0.3 |Francis Charette-Migneault |CWL Ad-hoc Execution |Adjust the definitions to make them applicable to CWL definitions that must combine workflow + execution |=== diff --git a/extensions/workflows/sections/clause_0_front_material.adoc b/extensions/workflows/sections/clause_0_front_material.adoc index 1b927b09..6a499a4d 100644 --- a/extensions/workflows/sections/clause_0_front_material.adoc +++ b/extensions/workflows/sections/clause_0_front_material.adoc @@ -52,6 +52,7 @@ All questions regarding this submission should be directed to the editors or the | *Name* | *Affiliation* | Jérôme Jacovella-St-Louis (editor) | Ecere Corporation | Panagiotis (Peter) A. Vretanos (editor) | CubeWerx Inc. +| Francis Charette-Migneault (editor) | Technologies Luqia, Centre de Recherche Informatique de Montréal (CRIM) | Gérald Fenoy | GeoLabs | Perry Peterson | University of Calgary | Marta Padilla Ruiz | University of Calgary @@ -59,7 +60,6 @@ All questions regarding this submission should be directed to the editors or the | Ryan Ahola | Natural Resources Canada | Stephan Meißl | EOX IT Services GmbH | Joan Masó Pau | Universitat Autònoma de Barcelona (CREAF) -| Francis Charette-Migneault | Technologies Luqia, Centre de Recherche Informatique de Montréal (CRIM) | Benjamin Proß | 52°North Spatial Information Research GmbH | Claudio Iacopino | European Space Agency (ESA) | Jeff Harrison | US Army Geospatial Center (AGC) diff --git a/extensions/workflows/sections/clause_12_cwl_workflows.adoc b/extensions/workflows/sections/clause_12_cwl_workflows.adoc index 2f675a55..51eb277b 100644 --- a/extensions/workflows/sections/clause_12_cwl_workflows.adoc +++ b/extensions/workflows/sections/clause_12_cwl_workflows.adoc @@ -1,24 +1,223 @@ [[section_cwl_workflows]] -== Common Workflow Language Definitions Conformance Class +== Common Workflow Language (CWL) Definitions Conformance Class === Requirement Class _Common Workflow Language Definitions_ -The _Common Workflow Language Definitions_ conformance class specifies the use of the -https://www.commonwl.org/v1.2/Workflow.html[Common Workflow Language (CWL) Workflow Description] as an alternative to an extended -_OGC API - Processes - Part 1: Core_ execution request to define an ad-hoc workflow -(a workflow that is not first required to be deployed as a process before being executed). +The _Common Workflow Language (CWL) Definitions_ conformance class specifies the use of the +https://www.commonwl.org/v1.2/Workflow.html[Common Workflow Language (CWL) - `Workflow`] or +the https://www.commonwl.org/v1.2/CommandLineTool.html[Common Workflow Language (CWL) - `CommandLineTool`] definitions +as the representation of the _Workflow and Chaining_ steps, combined with an execution request akin +to _OGC API - Processes - Part 1: Core_ to provide input and output parameters. -The capability to deploy a CWL workflow as a process using _OGC API - Processes - Part 2: Deploy, Replace, Undeploy_ -is already covered by a conformance class of Part 2. +However, due to the nature of CWL itself representing the workflow and chaining between processing steps, +an ad-hoc CWL workflow is **NOT** requested through the `POST /processes/{processId}/execution` endpoint, +as this would require a preexisting `{processId}`, defeating the purpose of an ad-hoc definition. -*TODO*: Verify that a CWL conformance class already exists or is planned for _Part 2_. +Instead, the ad-hoc CWL is requested either through the `POST /jobs` endpoint, +or a as a sub-workflow processing step under _another_ process on `POST /processes/{processId}/execution`. -*TODO*: Verify and describe which (if any) of the other conformance classes defined in this extension applies to ad-hoc CWL workflows. +NOTE: This definition is purposely aligned with +<> +(`POST /jobs`) and +<> +of <> to make integration seamless for server implementations that support multiple parts. +However, they are complementary and not strickly prerequisites of each other. include::../requirements/requirements_class_cwl-workflows.adoc[] -The following requirements describe the ability of an implementation to execute a CWL workflow in an ad-hoc manner and return its output, without requiring a prior deployment. +The following requirements describe the ability of an implementation to execute a CWL workflow in an ad-hoc manner +and return its output, without requiring a prior deployment. + +==== Ad-hoc CWL Execution through a Process + +include::../requirements/cwl-workflows/REQ_cwl-workflows_adhoc-cwl-process-execution.adoc[] + +For example, the following contents demonstrates two parts submitted to execute the `concatenate` process. +For the purpose of this example, this process simply concatenates the array of strings provided as input, +and return them into a single output. + +The first part of the multipart content is the execution body identified by the profile. +The second part is the ad-hoc CWL definition that fulfills a portion of the execution workflow, prior to its output +results being chained into the inputs of the parent `concatenate` process. + +The execution body indicates that the value of the first `messages` item for the `concatenate` process should +be obtained from the `cwl_output` output resulting from the execution chain. The ad-hoc CWL part contains a +literal value provided by `valueFrom` (using the standard CWL methodology). Therefore, the CWL would execute +the `echo` process and return its literal input through `cwl_output` (see `$(inputs.cwl_message)` reference). +That data (`"Hello, "` string) would then be chained into the `concatenate` process where referenced. +At the same time, other <> input definitions remain valid (i.e.: `value`, `href`, `collection`). +The resulting process would then produce `Hello, John Doe` as the output of the `concatenate` process. + +.Ad-hoc CWL execution chained into a parent Process +[source,httprequest] +---- +POST /processes/concatenate/execution HTTP/1.1 +Content-Type: multipart/related; boundary="sep" + +--sep +Content-Profile: +Content-Type: application/json + +{ + "inputs": { + "messages": [ + {"$output": "cwl_output"}, + {"value": "John Doe"} + ] + }, + "outputs": {"output": {}} +} + +--sep +Content-Type: application/cwl+json + +{ + "cwlVersion": "v1.2", + "class": "CommandLineTool", + "baseCommand": "echo", + "inputs": { + "cwl_message": { + "type": "string", + "inputBinding": { "valueFrom": "${ return 'Hello, '; }" } + } + }, + "outputs": { + "cwl_output": { + "type": "string", + "outputBinding": { "outputEval": "$(inputs.cwl_message)" } + } + } +} +--sep-- +---- + +NOTE: The above example demonstrates a basic CWL `class: CommandLineTool` for simplicity, but a more complex processing +chain involving CWL `class: Workflow`, sub-workflows, or any other supported CWL definition is also valid. Typical +chaining rules and syntax across CWL definitions apply normally according to its own specification. + +NOTE: One limitation of this approach is that a predefined and single "top-level" OGC API Process is required to receive +the CWL outputs. If an entire CWL definition is desired, without any parent process, or possibly scattering execution of +parallel graph operations, the > +approach should instead be considered. + +==== Ad-hoc CWL Execution through a Job + +include::../requirements/cwl-workflows/REQ_cwl-workflows_adhoc-cwl-job-execution.adoc[] + +For example, the following contents demonstrates two parts submitted for execution. +For the purpose of this example, this ad-hoc CWL simply outputs back the input that was provided (passthrough process). + +The first part of the multipart content is the execution body identified by the profile. +The second part is the ad-hoc CWL definition that fulfills the execution workflow. + +The `inputs` and `outputs` IDs specified are directly aligned with the ad-hoc CWL IDs of respective sections. +Therefore, the `"Hello World!"` string directly goes through the `cwl_message` of the CWL, which then uses `echo` +to pass it through the `cwl_output` via `$(inputs.cwl_message)`. The `cwl_output` is also indicated explicitly +for output selection in the usual <> fashion. + +.Ad-hoc CWL execution submitted as job +[source,httprequest] +---- +POST /jobs HTTP/1.1 +Content-Type: multipart/related; boundary="sep" + +--sep +Content-Profile: +Content-Type: application/json + +{ + "inputs": { + "cwl_message": "Hello World!" + }, + "outputs": { + "cwl_output": {} + } +} + +--sep +Content-Type: application/cwl+json + +{ + "cwlVersion": "v1.2", + "class": "CommandLineTool", + "baseCommand": "echo", + "inputs": { + "cwl_message": { + "type": "string", + "inputBinding": { "position": 1 } + } + }, + "outputs": { + "cwl_output": { + "type": "string", + "outputBinding": { "outputEval": "$(inputs.cwl_message)" } + } + } +} +--sep-- +---- + +NOTE: Although `inputs`/`outputs` are directly associated by ID, it is left up to implementations to perform any +relevant content-negotiation or data transformation between them as applicable. This standard does not impose any +strategy to perform these steps. + +==== Multipart Contents for Ad-hoc CWL Execution + +include::../requirements/cwl-workflows/REQ_cwl-workflows_adhoc-cwl-multipart-content.adoc[] + +include::../recommendations/cwl-workflows/PER_cwl-workflows_adhoc-cwl-multipart-alternate-encoding.adoc[] + +include::../recommendations/cwl-workflows/REC_cwl-workflows_adhoc-cwl-multipart-files.adoc[] + +For example, the following multipart execution request demonstrates how the additional data files are provided +with additional parts and referenced by the ad-hoc CWL definition to employ it at runtime. + +.Ad-hoc CWL execution with additional file +[source,httprequest] +---- +POST /jobs HTTP/1.1 +Content-Type: multipart/related; boundary="sep" + +--sep +Content-Profile: +Content-Type: application/json + +{ + "inputs": {}, + "outputs": {"info": {}} +} + +--sep +Content-Type: application/cwl+yaml + +cwlVersion: v1.2 +baseCommand: gdal +arguments: [vector, info] +inputs: + features: + type: File + loadContents: false + default: + class: File + path: "features.geojson" +outputs: + info: + type: stdout + +--sep +Content-Type: application/geo+json +Content-Disposition: filename="features.geojson" + +{"type": "FeatureCollection", "features": [...]} +--sep-- +---- + +==== Integration with Part 2: Deploy, Replace, Undeploy + +The capability to deploy a CWL workflow as a process using _OGC API - Processes - Part 2: Deploy, Replace, Undeploy_ +is already covered by conformance class <>. -==== Ad-hoc Common Workflow Language Execution +Although it is not strictly necessary to deploy and undeploy a process for ad-hoc CWL execution, a server supporting +_Part 2_ might also leverage this capability simultaneously to the execution request. -include::../requirements/cwl-workflows/REQ_cwl-workflows_adhoc-cwl-execution.adoc[] +include::../recommendations/cwl-workflows/PER_cwl-workflows_adhoc-cwl-deploy.adoc[] diff --git a/extensions/workflows/sections/clause_3_references.adoc b/extensions/workflows/sections/clause_3_references.adoc index 3875b64f..d7ecc292 100644 --- a/extensions/workflows/sections/clause_3_references.adoc +++ b/extensions/workflows/sections/clause_3_references.adoc @@ -9,7 +9,11 @@ For undated references, the latest edition of the normative document referred to References are to follow the Springer LNCS style, with the exception that optional information may be appended to references: DOIs are added after the date and web resource references may include an access date at the end of the reference in parentheses. See examples from Springer and OGC below. //// -* [[[OGC18-062r2,OGC 18-062r2]]], OGC API - Processes - Part 1: Core +* [[[OAProc-1,OGC 18-062r3]]] Pross, B., Vretanos, P.: OGC 18-062, *OGC API - Processes - Part 1: Core* (v2.0) + +* [[[OAProc-2,OGC 20-044]]] Panagiotis (Peter) A. Vretanos: OGC API - Processes - Part 2: Deploy, Replace, Undeploy (Draft). OGC 20-044, Open Geospatial Consortium, https://github.com/opengeospatial/ogcapi-processes/tree/master/extensions/deploy_replace_undeploy/standard[https://github.com/opengeospatial/ogcapi-processes/tree/master/extensions/deploy_replace_undeploy/standard] + +* [[[OAProc-4,OGC 24-051]]] Fenoy, G., Charette-Migneault, F.: OGC 24-051, *OGC API - Processes - Part 4: Job Management* * [[[OGC20-057,OGC 20-057]]], OGC API - Tiles - Part 1: Core (2022) @@ -17,8 +21,6 @@ References are to follow the Springer LNCS style, with the exception that option * [[[OGC19-086r5,OGC 19-086r5]]], OGC API - Environmental Data Retrieval - Part 1: Core (2022) -* [[[OGC20-044,OGC 20-044]]] Panagiotis (Peter) A. Vretanos: OGC API - Processes - Part 2: Deploy, Replace, Undeploy (Draft). OGC 20-044, Open Geospatial Consortium, https://github.com/opengeospatial/ogcapi-processes/tree/master/extensions/deploy_replace_undeploy/standard[https://github.com/opengeospatial/ogcapi-processes/tree/master/extensions/deploy_replace_undeploy/standard] - * [[[OGC19-072,OGC 19-072]]] Charles Heazel: OGC API - Common - Part 1: Core (Draft). OGC 19-072, Open Geospatial Consortium, http://docs.ogc.org/DRAFTS/19-072.html[http://docs.ogc.org/DRAFTS/19-072.html] * [[[OGC20-024,OGC 20-024]]] Charles Heazel: OGC API - Common - Part 2: Geospatial Data (Draft). OGC 20-024, Open Geospatial Consortium, http://docs.ogc.org/DRAFTS/20-024.html[http://docs.ogc.org/DRAFTS/20-024.html] @@ -33,3 +35,5 @@ References are to follow the Springer LNCS style, with the exception that option * [[[OGC20-058-fixme,OGC 20-058-fixme]]], Joan Masó, Jérôme Jacovella-St-Louis: OGC API - Maps - Part 1: Core (Draft). OGC 19-058, Open Geospatial Consortium, http://docs.ogc.org/DRAFTS/20-058.html[http://docs.ogc.org/DRAFTS/20-058.html] * [[[OGC21-038,OGC 21-038]]], Matthew B.J. Purss, Jérôme Jacovella-St-Louis: OGC API - Discrete Global Grid Systems - Part 1: Core (Draft). OGC 21-038, Open Geospatial Consortium, https://opengeospatial.github.io/ogcna-auto-review/21-038.html[https://opengeospatial.github.io/ogcna-auto-review/21-038.html] + +* [[rfc2387,IETF RFC 2387]] E. Levinson: IETF RFC 2387, *The MIME Multipart/Related Content-type*, 1998 http://tools.ietf.org/rfc/rfc2387.txt From 7ee572ddee3af46a56398e144a30dd5faf5f901a Mon Sep 17 00:00:00 2001 From: Francis Charette Migneault Date: Sat, 18 Jul 2026 11:15:15 -0400 Subject: [PATCH 2/3] add rec about documenting input href for additional file --- .../REC_cwl-workflows_adhoc-cwl-multipart-files.adoc | 11 +++++++++++ .../workflows/sections/clause_12_cwl_workflows.adoc | 4 +++- 2 files changed, 14 insertions(+), 1 deletion(-) diff --git a/extensions/workflows/recommendations/cwl-workflows/REC_cwl-workflows_adhoc-cwl-multipart-files.adoc b/extensions/workflows/recommendations/cwl-workflows/REC_cwl-workflows_adhoc-cwl-multipart-files.adoc index 4ea2724d..44dc8ce3 100644 --- a/extensions/workflows/recommendations/cwl-workflows/REC_cwl-workflows_adhoc-cwl-multipart-files.adoc +++ b/extensions/workflows/recommendations/cwl-workflows/REC_cwl-workflows_adhoc-cwl-multipart-files.adoc @@ -24,4 +24,15 @@ link:https://www.commonwl.org/v1.2/CommandLineTool.html#File[CWL File] supported to collect this file during execution (e.g., `glob`, `path`, `location`, etc.). -- +[.component,class=part] +-- +The part corresponding to the execution body SHOULD employ the corresponding `href` input +definition matching the specified file path from the resolved `Content-Disposition` header. +-- + ==== + +NOTE: Although explicit indication of the `href` for a given input might not always be strictly necessary +when the ad-hoc CWL definition can itself resolve it, it is recommended to indicate it for traceability +and explicit representation of the inputs through the _OGC API - Processes_ interface. This will allow +clients not aware of the _Part 3_ implementation details to still interact with jobs through _Part 1: Core_ interface. diff --git a/extensions/workflows/sections/clause_12_cwl_workflows.adoc b/extensions/workflows/sections/clause_12_cwl_workflows.adoc index 51eb277b..81c71d93 100644 --- a/extensions/workflows/sections/clause_12_cwl_workflows.adoc +++ b/extensions/workflows/sections/clause_12_cwl_workflows.adoc @@ -183,7 +183,9 @@ Content-Profile: Content-Type: application/json { - "inputs": {}, + "inputs": { + "features": {"href": "file://./features.geojson"} + }, "outputs": {"info": {}} } From 4c36fefdb1942d4467158d4f9e12692b5079c280 Mon Sep 17 00:00:00 2001 From: Francis Charette Migneault Date: Sat, 18 Jul 2026 11:23:45 -0400 Subject: [PATCH 3/3] fix typo --- .../REQ_cwl-workflows_adhoc-cwl-multipart-content.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/extensions/workflows/requirements/cwl-workflows/REQ_cwl-workflows_adhoc-cwl-multipart-content.adoc b/extensions/workflows/requirements/cwl-workflows/REQ_cwl-workflows_adhoc-cwl-multipart-content.adoc index d3c65c0b..975199ae 100644 --- a/extensions/workflows/requirements/cwl-workflows/REQ_cwl-workflows_adhoc-cwl-multipart-content.adoc +++ b/extensions/workflows/requirements/cwl-workflows/REQ_cwl-workflows_adhoc-cwl-multipart-content.adoc @@ -52,7 +52,7 @@ https://raw.githubusercontent.com/opengeospatial/ogcapi-processes/master/openapi [.component,class=part] -- -If a part employs a `Content-Location` header, it contents SHALL be retrieved from the provided URL, +If a part employs a `Content-Location` header, its contents SHALL be retrieved from the provided URL, unless the literal data contents are also provided explicitly within the part. --