RHIDP-9105: Best practices when creating a workflow

[jmagak]

IMPORTANT: Do Not Merge - To be merged by Docs Team Only

Version(s): 1.7, main

Issue: RHIDP-9105

Preview:

1.5. Best practices when creating a workflow

[rhdh-bot]

Updated preview: https://redhat-developer.github.io/red-hat-developers-documentation-rhdh/pr-1424/ @ 11/05/25 13:29:14

[gabriel-farache]

There are mentions of input.from, output.as, export.as but I do not understand their usage: there is the dataInputSchema field in the workflow which defines the input parameters the workflow needs, then the inputted arguments are accessible with the same names defined in the input schema.
Is the advised best practice to have a root field names input and then the actual inputs?
Same for output.as but for new data?
Which would mean the exports.as correspond the the new value of an already set field/key?
And what do you mean by "runtime expression "? Are those already defined in the workflow and any user may use it? I do not think there is such think in 0.8 version of the spec, does it come from 1.0 spec?

[gabriel-farache]

I think you used 1.0 spec to generate this doc; in https://serverlessworkflow.io/schemas/1.0.0/workflow.json there is

"export": {
      "type": "object",
      "title": "Export",
      "description": "Set the content of the context. .",
      "unevaluatedProperties": false,
      "properties": {
        "schema": {
          "$ref": "#/$defs/schema",
          "title": "ExportSchema",
          "description": "The schema used to describe and validate the workflow context."
        },
        "as": {
          "title": "ExportAs",
          "description": "A runtime expression, if any, used to export the output data to the context.",
          "oneOf": [
            {
              "type": "string"
            },
            {
              "type": "object"
            }
          ]
        }
      }
    },

which matches what is written here but does not exist in 0.8 AFAIK

[jmagak]

There are mentions of input.from, output.as, export.as but I do not understand their usage: there is the dataInputSchema field in the workflow which defines the input parameters the workflow needs, then the inputted arguments are accessible with the same names defined in the input schema. Is the advised best practice to have a root field names input and then the actual inputs? Same for output.as but for new data? Which would mean the exports.as correspond the the new value of an already set field/key? And what do you mean by "runtime expression "? Are those already defined in the workflow and any user may use it? I do not think there is such think in 0.8 version of the spec, does it come from 1.0 spec?

@gabriel-farache, here you will find the information on the Runtime Expression: https://github.com/serverlessworkflow/specification/blob/main/dsl.md#runtime-expressions, where the various arguments for each runtime expression (output.as, export.as, input.from) are mentioned, would you prefer that we exclude this information from the Best Practices documentation?

[gabriel-farache]

There are mentions of input.from, output.as, export.as but I do not understand their usage: there is the dataInputSchema field in the workflow which defines the input parameters the workflow needs, then the inputted arguments are accessible with the same names defined in the input schema. Is the advised best practice to have a root field names input and then the actual inputs? Same for output.as but for new data? Which would mean the exports.as correspond the the new value of an already set field/key? And what do you mean by "runtime expression "? Are those already defined in the workflow and any user may use it? I do not think there is such think in 0.8 version of the spec, does it come from 1.0 spec?

@gabriel-farache, here you will find the information on the Runtime Expression: https://github.com/serverlessworkflow/specification/blob/main/dsl.md#runtime-expressions, where the various arguments for each runtime expression (output.as, export.as, input.from) are mentioned, would you prefer that we exclude this information from the Best Practices documentation?

@jmagak the link relates to 1.0 specification whereas the sontaflow/Openshift Serverless Logic used 0.8 spec: https://github.com/serverlessworkflow/specification/blob/0.8.x/specification.md
AFAIK 1.0 will not there anytime soon so the doc must be based on 0.8 spec, or did I miss something @pkliczewski?

[pkliczewski]

@jmagak the link relates to 1.0 specification whereas the sontaflow/Openshift Serverless Logic used 0.8 spec: https://github.com/serverlessworkflow/specification/blob/0.8.x/specification.md AFAIK 1.0 will not there anytime soon so the doc must be based on 0.8 spec, or did I miss something @pkliczewski?

The team is working on 1.0 implementation but the delivery date it is not clear yet. Let's link to 0.8 for now and we can update as soon as 1.0 is implemented.

[gabriel-farache]

I see references to 1.0 spec that do not exist in 0.8, could you check?

[pabel-rh]

Some minor comments.

[jmagak]

/cherry-pick release-1.8

[openshift-cherrypick-robot]

@jmagak: once the present PR merges, I will cherry-pick it on top of release-1.8 in a new PR and assign it to you.

In response to this:

/cherry-pick release-1.8

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[jmagak]

/cherry-pick release-1.7

[openshift-cherrypick-robot]

@jmagak: once the present PR merges, I will cherry-pick it on top of release-1.7 in a new PR and assign it to you.

In response to this:

/cherry-pick release-1.7

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[openshift-cherrypick-robot]

@jmagak: #1424 failed to apply on top of branch "release-1.8":

Applying: Update the best practices
.git/rebase-apply/patch:17: new blank line at EOF.
+
warning: 1 line adds whitespace errors.
Using index info to reconstruct a base tree...
M	assemblies/assembly-orchestrator-rhdh.adoc
Falling back to patching base and 3-way merge...
Auto-merging assemblies/assembly-orchestrator-rhdh.adoc
CONFLICT (content): Merge conflict in assemblies/assembly-orchestrator-rhdh.adoc
error: Failed to merge in the changes.
hint: Use 'git am --show-current-patch=diff' to see the failed patch
hint: When you have resolved this problem, run "git am --continue".
hint: If you prefer to skip this patch, run "git am --skip" instead.
hint: To restore the original branch and stop patching, run "git am --abort".
hint: Disable this message with "git config advice.mergeConflict false"
Patch failed at 0001 Update the best practices

In response to this:

/cherry-pick release-1.8

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[openshift-cherrypick-robot]

@jmagak: #1424 failed to apply on top of branch "release-1.7":

Applying: Update the best practices
.git/rebase-apply/patch:17: new blank line at EOF.
+
warning: 1 line adds whitespace errors.
Using index info to reconstruct a base tree...
M	assemblies/assembly-orchestrator-rhdh.adoc
Falling back to patching base and 3-way merge...
Auto-merging assemblies/assembly-orchestrator-rhdh.adoc
CONFLICT (content): Merge conflict in assemblies/assembly-orchestrator-rhdh.adoc
error: Failed to merge in the changes.
hint: Use 'git am --show-current-patch=diff' to see the failed patch
hint: When you have resolved this problem, run "git am --continue".
hint: If you prefer to skip this patch, run "git am --skip" instead.
hint: To restore the original branch and stop patching, run "git am --abort".
hint: Disable this message with "git config advice.mergeConflict false"
Patch failed at 0001 Update the best practices

In response to this:

/cherry-pick release-1.7

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.