Update the best practices

Author: GitHub Actions

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

@@ -3,4 +3,88 @@
 [id="con-best-practices-for-creating-workflows.adoc_{context}"]
 = Best practices when creating a workflow
 
-Review the following best practices when you create a seamless integration of workflows with the {product-custom-resource-type} Orchestrator UI and adherence to Serverless Workflow DSL principles. You can apply one or more of these practices in your environment.
+Here are some best practices when creating workflows while adhering to Serverless Workflow DSL principles.
+
+Workflow design principles based on Serverless Workflow (DSL)::
+
+The Serverless Workflow Domain Specific Language (DSL) prioritizes clarity and ease of use.
+
+* Priority of constituencies
++
+When developing workflows or APIs, ensure the needs of the author (workflow writer) come first. The constituencies are prioritized as follows: Authors > Operators > Implementors > Specifications writers.
+
+* Linguistic fluency and clarity
++
+**   Embrace linguistic fluency for enhanced readability and understanding.
+**   Utilize imperative verbs to convey actions directly and clearly.
+**   Opt for universally understood terms to improve accessibility and comprehension, avoiding technical jargon wherever possible.
+
+* Structure and Extensibility
++
+** Employ implicit default behaviors to reduce redundancy and streamline workflow definitions, sparing authors from unnecessary repetition.
+** Encourage the declaration of components inline for situations where reusability is unnecessary.
+** Enable the declaration and effortless import of shared components by supporting external references.
+** Prioritize flexibility over strong-typed enumerations for enhanced extensibility and adaptability across different runtime environments.
+
+Data flow and runtime management::
+
+. Tasks and execution
++
+** Tasks are the fundamental computing units of a workflow. The DSL defines several default task types that runtimes must implement, including `Call`, `Do`, `Emit`, `For`, `Fork`, `Listen`, `Raise`, `Run`, `Set`, `Switch`, `Try`, and `Wait`.
+
+. Data transformations
++
+To ensure data flows in a controlled and efficient manner, transformations can be applied at strategic points:
+
+** Workflow Input Validation/Transformation: Before the workflow starts, validate input data against the `input.schema`. Input data can be transformed using the top-level `input.from` expression to pass only relevant data to the workflow context.
+** Task Input/Output Transformation: Before a task executes, its input can be transformed using the task's `input.from` expression to match specific task requirements. After the task completes, its output can be transformed using the `output.as` runtime expression before being passed to the next task.
+** Context Management: Use the `export.as` runtime expression to update the workflow's context. This evaluates the transformed task output, helping to keep the context clean by removing unnecessary data.
+** Workflow output transformation: Finally, transform the overall workflow output using `output.as` before returning it to the caller, ensuring the final output is concise and relevant.
+
+. Security (Secrets)
++
+** Use secrets with caution: Incorporating secrets in expressions or passing them as call inputs may inadvertently expose sensitive information.
+** Secrets can only be used in the `input.from` runtime expression to prevent unintentional bleeding.
+
+Fault tolerance and error handling::
+
+Serverless Workflow is designed with resilience in mind to recover gracefully from failures.
+
+** Error Description: Errors should be described using the **Problem Details RFC**. The `instance` property should be used as a JSON Pointer to identify the specific component that raised the error.
+** Standard Errors: Use standard error types defined by the specification (e.g., timeouts) to ensure consistent behavior across different runtimes.
+** Retries: For transient errors (like a 503 `Service Unavailable`), utilize the built-in mechanism to **retry a faulted task** (via a `try` block) to allow for graceful recovery.
+** Timeouts: Workflows and tasks can be configured to timeout. Upon timeout, execution must be interrupted, and an error must be raised with the type **`https://serverlessworkflow.io/spec/1.0.0/errors/timeout`** and status **408**.
+
+Orchestrator UI integration best practices::
+
+To effectively display results, output generated by the user interface, or facilitate the chaining of workflow executions, the workflow must deliver its output data in a recognized structured format defined by the `WorkflowResult` schema.
+
+. Workflow output schema
++
+..  Placement of Results: The output intended for next processing **should be placed under the `data.result` property**.
+..  Schema Reference: The output schema file (`schemas/workflow-output-schema.json`) should reference the `WorkflowResult` schema.
+..  Outputs Definition: Include an `outputs` section in the workflow definition containing human-readable key/value pairs that will be displayed in the UI.
++
+.Example structure for workflow output data injection:
+
+[source,yaml]
+----
+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
+----
+
+
+. Deprecation notice for workflow types
++
+** Deprecation Notice: From Orchestrator release version 1.7, Workflow Types will be retired. All workflows will act as infrastructure workflows, and no workflow will act as an assessment workflow. Any references to assessment workflows (such as in the `nextWorkflows` property example above) will become obsolete.