RHIDP-9105: Best practices when creating a workflow

assemblies/assembly-orchestrator-rhdh.adoc

@@ -45,4 +45,7 @@ include::modules/orchestrator/proc-helm-install-components-orchestrator-plugin.a
 include::modules/orchestrator/proc-manual-install-components-orchestrator-plugin.adoc[leveloffset=+2]
 
 // {product-very-short} helper script
-include::modules/orchestrator/proc-helper-script-overview.adoc[leveloffset=+2]
+include::modules/orchestrator/proc-helper-script-overview.adoc[leveloffset=+2]
+
+// best practices when creating workflows
+include::modules/orchestrator/ref-best-practices-for-creating-workflows.adoc[leveloffset=+1]

modules/orchestrator/ref-best-practices-for-creating-workflows.adoc

@@ -0,0 +1,91 @@
+:_mod-docs-content-type: CONCEPT
+
+[id="ref-best-practices-for-creating-workflows.adoc_{context}"]
+= Best practices when creating serverless workflows
+
+Create effective serverless workflows using thoughtful approaches to design, handle data, and manage error by following these best practices based on the Serverless Workflow Domain Specific Language (DSL) principles. These principles help you to build robust workflows.
+
+Workflow design principles::
++
+The Serverless Workflow DSL prioritizes clarity and ease of use when writing workflows.
+
+Priority of constituencies:::
++
+When developing workflows or APIs, ensure the needs of the author (workflow writer) come first. The constituencies are prioritized in the following order: Authors > Operators > Implementors > Specifications writers.
+
+Linguistic fluency and clarity:::
++
+** Use imperative verbs such as `Call`, `Emit`, `For`, `Fork`, `Raise`, `Run`, `Set`, `Switch`, and `Wait`. These simple, universally understood terms make your workflow simple to read and understand.
+
+Structure and Extensibility:::
++
+** Use implicit default behaviors to reduce redundancy.
+** Declare components inline if they are not reusable to keep the definition self-contained.
+** Use external references to import and reuse shared components, which promotes a modular design.
+** Prioritize flexibility over strict enumerations to ensure extensibility and adaptability across different runtime environments.
+
+Data flow and runtime management::
++
+Controlling data flow is critical for efficient workflows. Tasks are the fundamental computing units of a workflow. The Domain Specific Language defines several default task types that runtimes must do. These include `Do`, `Listen`, `Raise`, `Run`, `Try`, and `Wait`.
++
+You can apply data transformations at several key points:
+
+Workflow input validation::: Before the workflow starts, validate input data against the `input.schema` and use the top-level `input.from` expression to filter out data that is not relevant data to the workflow context.
+
+Task Input/Output::: Before a task runs, transform its input using the `input.from` to match specific task requirements. After the task completes, use `output.as` runtime expression to transform its output before it is passed to the next task.
+
+Context Management::: Use the `export.as` runtime expression to update the context of the workflow. This evaluates the transformed task output, making sure the final output is accurate and relevant.
+
+Workflow output transformation::: Finally, transform the overall workflow output using `output.as` before returning it to the caller, making sure the final output is relevant.
+
+Security and error handling::
++
+Secrets::: Use Secrets with caution. Use them within the `input.from` runtime expression to prevent them from being unintentionally exposed. Avoid passing them directly in expressions or call inputs as this might expose sensitive information.
+
+Fault tolerance and error handling::: Serverless Workflow is designed with resilience in mind to recover from failures.
++
+Standard Errors:::: Use _standard error types_, such as timeouts, to categorize errors consistently across different runtimes. These also facilitate seamless migration from one runtime environment to another.
+Describe errors using the _Problem Details Request for Comments (RFC)_, with the `instance` property pointing to the component causing the error.
+
+Retries:::: Use `try` blocks to implement retries for transient errors, such as a temporary network issue.
+
+Timeouts:::: Configure timeouts for workflows and individual tasks. If a timeout occurs, you must interrupt the execution, and a standard timeout error with the type `https://serverlessworkflow.io/spec/0.8/errors/timeout` and status `408`is raised.
+
+Orchestrator UI integration best practices::
++
+For your workflow results to be effectively displayed in the Orchestrator UI and to facilitate chaining of workflows, you must structure the output data according to the `WorkflowResult` schema. Additionally, include any error information as part of the workflow output so the UI and subsequent workflows can handle them accordingly.
++
+Workflow output schema:::
++
+Results placement:::: The primary output intended for subsequent processing should be placed under the `data.result` property.
+
+Schema reference:::: Your output schema file (`schemas/workflow-output-schema.json`) should reference the `WorkflowResult` schema.
+
+Outputs definition:::: Include an `outputs` section in your workflow definition. This section contains human-readable key/value pairs that the UI will display.
++
+Structure of workflow:
++
+[source,yaml]
+----
+id: my-workflow
+version: "0.8"
+specVersion: "0.8"
+name: My Workflow
+start: ImmediatelyEnd
+extensions:
+  - extensionid: workflow-output-schema
+    outputSchema: schemas/workflow-output-schema.json
+states:
+  - name: ImmediatelyEnd
+     type: inject
+     data:
+       result:
+          message: A human-readable description of the successful status. Or an error.
+          outputs:
+            - key: Foo Bar human readable name which will be shown in the UI
+              value: Example string value produced on the output. This might be an input for a next workflow.
+          nextWorkflows:
+            - id: my-next-workflow-id
+              name: Next workflow name suggested if this is an assessment workflow. Human readable, it's text does not need to match true workflow name.
+    end: true
+----