This is an automated email from the ASF dual-hosted git repository.
dhanak pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-kie-kogito-docs.git
The following commit(s) were added to refs/heads/main by this push:
new c20ee24d6 kie-kogito-docs#695: Holistic review follow-up (#698)
c20ee24d6 is described below
commit c20ee24d6d42774ac4c5be07a7ef177d17e5ece8
Author: Dominik Hanák <[email protected]>
AuthorDate: Tue Jan 21 18:26:38 2025 +0100
kie-kogito-docs#695: Holistic review follow-up (#698)
* Enhance install-serverless-operator guide
* Fix kn-plugin-workflow-overview
* Fix order of sections to reflect the users path
* Improve the introduction guide
* Add Exectuing a workflow procedure
* Slim down the testing section
---
serverlessworkflow/antora.yml | 2 +-
serverlessworkflow/modules/ROOT/nav.adoc | 49 +++---
.../getting-started-requirement.adoc | 2 +-
.../operator/install-serverless-operator.adoc | 13 +-
...-serverless-workflow-specification-support.adoc | 2 +-
.../understanding-workflow-error-handling.adoc | 2 +-
.../ROOT/pages/core/working-with-callbacks.adoc | 2 +-
.../ROOT/pages/core/working-with-parallelism.adoc | 2 +-
...introduction-sonataflow-development-guide.adoc} | 109 ++++++++-----
.../getting-started/preparing-environment.adoc | 2 +-
serverlessworkflow/modules/ROOT/pages/index.adoc | 2 +-
.../orchestration-of-openapi-based-services.adoc | 2 +-
.../kn-plugin-workflow-overview.adoc | 174 +++++++++++----------
13 files changed, 202 insertions(+), 161 deletions(-)
diff --git a/serverlessworkflow/antora.yml b/serverlessworkflow/antora.yml
index 72cfe71bd..60bdfae4f 100644
--- a/serverlessworkflow/antora.yml
+++ b/serverlessworkflow/antora.yml
@@ -129,7 +129,7 @@ asciidoc:
open_api_swagger_spec_url: https://swagger.io/docs/specification
quarkus_openapi_gen_url:
https://github.com/quarkiverse/quarkus-openapi-generator
kn_workflow_plugin_releases_url:
https://kie.apache.org/docs/start/download#sonataflow-knative-plugin
- kie_tools_releases_page_url:
https://github.com/apache/incubator-kie-tools/releases
+ kie_tools_releases_page_url:
https://kie.apache.org/docs/start/download#sonataflow-knative-plugin
quarkus_guides_base_url: https://quarkus.io/guides
quarkus_guides_kafka_url: https://quarkus.io/guides/kafka
quarkus_guides_building_native:
https://quarkus.io/guides/building-native-image
diff --git a/serverlessworkflow/modules/ROOT/nav.adoc
b/serverlessworkflow/modules/ROOT/nav.adoc
index 3aa820c9c..1d5434068 100644
--- a/serverlessworkflow/modules/ROOT/nav.adoc
+++ b/serverlessworkflow/modules/ROOT/nav.adoc
@@ -22,7 +22,7 @@
** xref:getting-started/production-environment.adoc[]
* Getting Started
** xref:getting-started/getting-familiar-with-our-tooling.adoc[]
-**
xref:getting-started/create-your-first-workflow-service-with-kn-cli-and-vscode.adoc[]
+** xref:getting-started/introduction-sonataflow-development-guide.adoc[]
** xref:getting-started/java-embedded-workflows.adoc[]
* Core Concepts
** xref:core/cncf-serverless-workflow-specification-support.adoc[]
@@ -44,29 +44,6 @@
***
xref:tooling/serverless-logic-web-tools/serverless-logic-web-tools-openshift-integration.adoc[Integration
with OpenShift]
***
xref:tooling/serverless-logic-web-tools/serverless-logic-web-tools-redhat-application-services-integration.adoc[Integration
with Service Registries]
***
xref:tooling/serverless-logic-web-tools/serverless-logic-web-tools-deploy-projects.adoc[Deployment]
-* Service Orchestration
-**
xref:service-orchestration/orchestration-of-openapi-based-services.adoc[OpenAPI]
-***
xref:service-orchestration/configuring-openapi-services-endpoints.adoc[Advanced
Configuration]
-*** xref:service-orchestration/working-with-openapi-callbacks.adoc[Callbacks]
-** xref:service-orchestration/troubleshooting.adoc[Troubleshooting]
-* Event Orchestration
-** xref:eventing/orchestration-of-asyncapi-based-services.adoc[AsyncAPI]
-** xref:eventing/event-correlation-with-workflows.adoc[Event Correlation]
-* Security
-** Client Authentication
-*** xref:security/authention-support-for-openapi-services.adoc[OpenAPI
Authentication]
-*** xref:security/orchestrating-third-party-services-with-oauth2.adoc[OpenAPI
OAuth2]
-* Executing, Testing and Troubleshooting
-** Executing and Testing Workflows
-***
xref:testing-and-troubleshooting/quarkus-dev-ui-extension/quarkus-dev-ui-overview.adoc[Developer
UI]
-****
xref:testing-and-troubleshooting/quarkus-dev-ui-extension/quarkus-dev-ui-workflow-instances-page.adoc[Workflow
Instances]
-****
xref:testing-and-troubleshooting/quarkus-dev-ui-extension/quarkus-dev-ui-workflow-definition-page.adoc[Workflow
Definitions]
-****
xref:testing-and-troubleshooting/quarkus-dev-ui-extension/quarkus-dev-ui-monitoring-page.adoc[Monitoring]
-****
xref:testing-and-troubleshooting/quarkus-dev-ui-extension/quarkus-dev-ui-custom-dashboard-page.adoc[Dashboards]
-*** xref:testing-and-troubleshooting/kn-plugin-workflow-overview.adoc[Command
Line]
-* Persistence
-** xref:persistence/core-concepts.adoc[Core concepts]
-// * Java Workflow Library TODO: https://issues.redhat.com/browse/KOGITO-9454
* xref:cloud/index.adoc[Cloud]
** xref:cloud/custom-ingress-authz.adoc[Securing Workflows]
**
xref:cloud/deploying-sonataflow-management-console-on-kubernetes.adoc[Deploying
Management Console on Kubernetes]
@@ -90,6 +67,28 @@
**** xref:cloud/operator/sonataflow-metrics.adoc[Prometheus Metrics for
Workflows]
*** xref:cloud/operator/known-issues.adoc[Roadmap and Known Issues]
*** xref:cloud/operator/add-custom-ca-to-a-workflow-pod.adoc[Add Custom CA to
Workflow Pod]
+* Service Orchestration
+**
xref:service-orchestration/orchestration-of-openapi-based-services.adoc[OpenAPI]
+***
xref:service-orchestration/configuring-openapi-services-endpoints.adoc[Advanced
Configuration]
+*** xref:service-orchestration/working-with-openapi-callbacks.adoc[Callbacks]
+** xref:service-orchestration/troubleshooting.adoc[Troubleshooting]
+* Event Orchestration
+** xref:eventing/orchestration-of-asyncapi-based-services.adoc[AsyncAPI]
+** xref:eventing/event-correlation-with-workflows.adoc[Event Correlation]
+* Security
+** Client Authentication
+*** xref:security/authention-support-for-openapi-services.adoc[OpenAPI
Authentication]
+*** xref:security/orchestrating-third-party-services-with-oauth2.adoc[OpenAPI
OAuth2]
+* Executing, Testing and Troubleshooting
+** xref:testing-and-troubleshooting/kn-plugin-workflow-overview.adoc[KN CLI
Workflow plugin]
+**
xref:testing-and-troubleshooting/quarkus-dev-ui-extension/quarkus-dev-ui-overview.adoc[Developer
UI]
+***
xref:testing-and-troubleshooting/quarkus-dev-ui-extension/quarkus-dev-ui-workflow-instances-page.adoc[Workflow
Instances]
+***
xref:testing-and-troubleshooting/quarkus-dev-ui-extension/quarkus-dev-ui-workflow-definition-page.adoc[Workflow
Definitions]
+***
xref:testing-and-troubleshooting/quarkus-dev-ui-extension/quarkus-dev-ui-monitoring-page.adoc[Monitoring]
+***
xref:testing-and-troubleshooting/quarkus-dev-ui-extension/quarkus-dev-ui-custom-dashboard-page.adoc[Dashboards]
+* Persistence
+** xref:persistence/core-concepts.adoc[Core concepts]
+// * Java Workflow Library TODO: https://issues.redhat.com/browse/KOGITO-9454
* Integrations
** xref:integrations/core-concepts.adoc[]
* Job Service
@@ -98,7 +97,7 @@
** xref:data-index/data-index-core-concepts.adoc[Core concepts]
** xref:data-index/data-index-service.adoc[Standalone service]
* Use Cases
-** xref:use-cases/advanced-developer-use-cases/index.adoc[Advanced Development
Use Cases of {product_name} applications using Quarkus and Java]
+** xref:use-cases/advanced-developer-use-cases/index.adoc[{product_name}
applications development using Quarkus and Java]
*** Getting started
****
xref:use-cases/advanced-developer-use-cases/getting-started/create-your-first-workflow-service.adoc[]
****
xref:use-cases/advanced-developer-use-cases/getting-started/create-your-first-workflow-project.adoc[]
diff --git
a/serverlessworkflow/modules/ROOT/pages/_common-content/getting-started-requirement.adoc
b/serverlessworkflow/modules/ROOT/pages/_common-content/getting-started-requirement.adoc
index 02f06e165..71a366c71 100644
---
a/serverlessworkflow/modules/ROOT/pages/_common-content/getting-started-requirement.adoc
+++
b/serverlessworkflow/modules/ROOT/pages/_common-content/getting-started-requirement.adoc
@@ -1,3 +1,3 @@
* A workflow project is created.
+
-For more information about creating a workflow project, see
xref:getting-started/create-your-first-workflow-service-with-kn-cli-and-vscode.adoc[Creating
your first workflow project].
\ No newline at end of file
+For more information about creating a workflow project, see
xref:getting-started/introduction-sonataflow-development-guide.adoc[Creating
your first workflow project].
\ No newline at end of file
diff --git
a/serverlessworkflow/modules/ROOT/pages/cloud/operator/install-serverless-operator.adoc
b/serverlessworkflow/modules/ROOT/pages/cloud/operator/install-serverless-operator.adoc
index aff342947..addd72950 100644
---
a/serverlessworkflow/modules/ROOT/pages/cloud/operator/install-serverless-operator.adoc
+++
b/serverlessworkflow/modules/ROOT/pages/cloud/operator/install-serverless-operator.adoc
@@ -5,13 +5,14 @@
:keywords: kogito, sonataflow, workflow, serverless, operator, kubernetes,
minikube, openshift, containers
// links
+:kubernetes_version: {kubernetes_version}
:openshift_operator_install_url:
https://docs.openshift.com/container-platform/4.13/operators/admin/olm-adding-operators-to-cluster.html
:openshift_operator_uninstall_url:
https://docs.openshift.com/container-platform/4.13/operators/admin/olm-deleting-operators-from-cluster.html
:kubernetes_operator_install_url:
https://operatorhub.io/how-to-install-an-operator
:kubernetes_operator_uninstall_url:
https://olm.operatorframework.io/docs/tasks/uninstall-operator/
:operatorhub_url: https://operatorhub.io/
-This guide describes how to install the {operator_name} in a Kubernetes or
OpenShift cluster. The operator is in an
xref:cloud/operator/known-issues.adoc[early development stage] (community only)
and has been tested on OpenShift {openshift_version_min}+, Kubernetes
{kubernetes_version}+, and link:{minikube_url}[Minikube].
+This guide describes how to install the {operator_name} in a Kubernetes or
OpenShift cluster. The operator is in an
xref:cloud/operator/known-issues.adoc[early development stage] (community only)
and has been tested on OpenShift {openshift_version_min}+ , Kubernetes
{kubernetes_version}+ , {minikube_url}[Minikube] and {kind_install_url}[Kind].
.Prerequisites
* A Kubernetes or OpenShift cluster with admin privileges and `kubectl`
installed.
@@ -64,7 +65,9 @@ To install the {product_name} Operator, you can use the
following command:
----
kubectl create -f
{kogito_operator_repository_rawcontent_url}/{operator_version}/operator.yaml
----
+
Replace `<version>` with specific version if needed:
+[source,shell,subs="attributes+"]
----
kubectl create -f
{kogito_operator_repository_rawcontent_url}/<version>/operator.yaml
----
@@ -120,8 +123,14 @@ To uninstall the correct version of the operator, first
you must get the current
.Getting the operator version
[source,shell,subs="attributes+"]
----
-kubectl get deployment {operator_controller_manager_deployment_name} -n
sonataflow-operator-system -o
jsonpath="{.spec.template.spec.containers[?(@.name=='manager')].image}"
+kubectl get deployment {operator_controller_manager_deployment_name} \
+ -n sonataflow-operator-system \
+ -o jsonpath="{.spec.template.spec.containers[?(@.name=='manager')].image}"
+----
+Expected output:
+[source,shell,subs="attributes+"]
+----
{sonataflow_operator_imagename}:{operator_version}
----
diff --git
a/serverlessworkflow/modules/ROOT/pages/core/cncf-serverless-workflow-specification-support.adoc
b/serverlessworkflow/modules/ROOT/pages/core/cncf-serverless-workflow-specification-support.adoc
index c35c6f16f..39819bd53 100644
---
a/serverlessworkflow/modules/ROOT/pages/core/cncf-serverless-workflow-specification-support.adoc
+++
b/serverlessworkflow/modules/ROOT/pages/core/cncf-serverless-workflow-specification-support.adoc
@@ -266,7 +266,7 @@ Secrets are associated with the
link:{quarkus_config_guide_url}[Quarkus Configur
== Additional resources
-*
xref:getting-started/create-your-first-workflow-service-with-kn-cli-and-vscode.adoc[]
+* xref:getting-started/introduction-sonataflow-development-guide.adoc[]
* xref:getting-started/getting-familiar-with-our-tooling.adoc[Getting familiar
with {product_name} tooling]
include::../../pages/_common-content/report-issue.adoc[]
diff --git
a/serverlessworkflow/modules/ROOT/pages/core/understanding-workflow-error-handling.adoc
b/serverlessworkflow/modules/ROOT/pages/core/understanding-workflow-error-handling.adoc
index 8ae0d7dd0..fa6faee18 100644
---
a/serverlessworkflow/modules/ROOT/pages/core/understanding-workflow-error-handling.adoc
+++
b/serverlessworkflow/modules/ROOT/pages/core/understanding-workflow-error-handling.adoc
@@ -185,7 +185,7 @@ The `finish` state in the
`serverless-workflow-error-quarkus` example applicatio
== Additional resources
-*
xref:getting-started/create-your-first-workflow-service-with-kn-cli-and-vscode[]
+* xref:getting-started/introduction-sonataflow-development-guide[]
include::../../pages/_common-content/report-issue.adoc[]
diff --git
a/serverlessworkflow/modules/ROOT/pages/core/working-with-callbacks.adoc
b/serverlessworkflow/modules/ROOT/pages/core/working-with-callbacks.adoc
index 4f9f02e52..ca3d66204 100644
--- a/serverlessworkflow/modules/ROOT/pages/core/working-with-callbacks.adoc
+++ b/serverlessworkflow/modules/ROOT/pages/core/working-with-callbacks.adoc
@@ -17,7 +17,7 @@ The workflow correlation described in this document focuses
on the former mechan
== Additional resources
-*
xref:getting-started/create-your-first-workflow-service-with-kn-cli-and-vscode.adoc[]
+* xref:getting-started/introduction-sonataflow-development-guide.adoc[]
* xref:eventing/event-correlation-with-workflows.adoc[Event correlation in
{product_name}]
*
xref:use-cases/advanced-developer-use-cases/callbacks/callback-state-example.adoc[]
*
xref:use-cases/advanced-developer-use-cases/getting-started/create-your-first-workflow-service.adoc[]
diff --git
a/serverlessworkflow/modules/ROOT/pages/core/working-with-parallelism.adoc
b/serverlessworkflow/modules/ROOT/pages/core/working-with-parallelism.adoc
index a37347f1e..d85e7a867 100644
--- a/serverlessworkflow/modules/ROOT/pages/core/working-with-parallelism.adoc
+++ b/serverlessworkflow/modules/ROOT/pages/core/working-with-parallelism.adoc
@@ -270,6 +270,6 @@ The parallel workflow data shows the concatenated string as
result, but in this
== Additional resources
-*
xref:getting-started/create-your-first-workflow-service-with-kn-cli-and-vscode.adoc[Creating
your first workflow service]
+* xref:getting-started/introduction-sonataflow-development-guide.adoc[Creating
your first workflow service]
include::../../pages/_common-content/report-issue.adoc[]
\ No newline at end of file
diff --git
a/serverlessworkflow/modules/ROOT/pages/getting-started/create-your-first-workflow-service-with-kn-cli-and-vscode.adoc
b/serverlessworkflow/modules/ROOT/pages/getting-started/introduction-sonataflow-development-guide.adoc
similarity index 55%
rename from
serverlessworkflow/modules/ROOT/pages/getting-started/create-your-first-workflow-service-with-kn-cli-and-vscode.adoc
rename to
serverlessworkflow/modules/ROOT/pages/getting-started/introduction-sonataflow-development-guide.adoc
index 2a07c7329..34cb07e35 100644
---
a/serverlessworkflow/modules/ROOT/pages/getting-started/create-your-first-workflow-service-with-kn-cli-and-vscode.adoc
+++
b/serverlessworkflow/modules/ROOT/pages/getting-started/introduction-sonataflow-development-guide.adoc
@@ -1,36 +1,46 @@
-= Creating and running workflow projects using KN CLI and Visual Studio Code
+= Introduction to {product_name} development
-This guide showcases using the Knative Workflow CLI plugin and Visual Studio
code to create & run {product_name} projects.
+This guide showcases the {product_name} Workflow CLI plugin and Apache KIE
Serverless Workflow Visual Studio code extension to create, run & deploy
{product_name} projects on your local environment and walks you trhought the
recommended development loop of workflow applications.
.Prerequisites
* You have set up your environment according to the
xref:getting-started/preparing-environment.adoc#proc-minimal-local-environment-setup[minimal
environment setup] guide.
-* Install link:{k9s_url}[k9scli.io] for easier inspection of your application
resources in the cluster. This is optional, you can use any tool you are
familiar with in this regard.
+
[[proc-creating-app-with-kn-cli]]
-== Creating a workflow project with Visual Studio Code and KN CLI
+== Creating a workflow project with KN CLI
Use the `create` command with kn workflow to scaffold a new SonataFlow project.
-* Navigate to your development directory and create your project.
+.Procedure
+. Navigate to your development directory and create your project.
[source,bash]
++
----
kn workflow create -n my-sonataflow-project
----
-* This will create a folder with name `my-sonataflow-project` and a sample
workflow `workflow.sw.json`
+. This will create a folder with name `my-sonataflow-project` and a sample
workflow `workflow.sw.json`
[source,bash]
++
----
cd ./my-sonataflow-project
----
-* Open the folder in Visual Studio Code and examine the created
`workflow.sw.json` using our extension.
+. Open the folder in Visual Studio Code and examine or the created
`workflow.sw.json` using the editor provided by the extension.
+[source,bash]
++
+----
+code workflow.sw.json
+----
Now you can run the project and execute the workflow.
[[proc-running-app-with-kn-cli]]
-== Running a Workflow project with Visual Studio Code and KN CLI
+== Running a workflow project with KN CLI
-Use the `run` command with kn workflow to build and run the {product_name}
project in local development mode.
+Use the `run` command with kn workflow to build and run the {product_name}
project locally in development mode.
-* Run the project.
+.Procedure
+. Run the project.
++
[source,bash]
----
kn workflow run
@@ -38,32 +48,69 @@ kn workflow run
* The Development UI will be accessible at `localhost:8080/q/dev`
* You can now work on your project. Any changes will be picked up by the hot
reload feature.
* See
xref:testing-and-troubleshooting/quarkus-dev-ui-extension/quarkus-dev-ui-workflow-instances-page.adoc[Workflow
instances] guide on how to run workflows via Development UI.
-* Once you are done developing your project navigate to the terminal that is
running the `kn workflow run` command and hit `Ctlr+C` to stop the development
environment.
+* Once you are done developing your project navigate to the terminal that is
running the `kn workflow run` command and hit `Ctrl+C` to stop the development
environment.
You can use any editor to develop your workflow to suit your use case. We
recommend getting familiar with
xref:../core/cncf-serverless-workflow-specification-support.adoc[] and guides
in `Core` chapter first.
-To deploy the finished project to a local cluster, proceed to the next section.
+.Executing a workflow
+. To test your running workflow project, access the Swagger UI on
`localhost:8080/q/swagger-ui` to examine available endpoints.
+. In order to execute the workflow once, run:
+[source,bash]
+----
+curl -X 'POST' \
+ 'localhost:8080/hello' \
+ -H 'accept: */*' \
+ -H 'Content-Type: application/json' \
+ -d '{
+ "workflowdata": {}
+}'
+----
+. You should see a similar response:
++
+[source,bash]
+----
+{"id": "<UUID>", "workflowdata" : {"message":"Hello World"}}
+----
+
+
+To deploy the finished project to kubernetes cluster, proceed to the next
section.
[[proc-deploying-app-with-kn-cli]]
-== Deploying a workflow project with Visual Studio Code and KN CLI
+== Deploying a workflow project with KN CLI
+
+.Prerequisites
+* You are logged into your kubernetes cluster or started one locally according
to the
xref:getting-started/preparing-environment.adoc#proc-starting-cluster-fo-local-development[starting
cluster for local development] guide.
+* You have installed {operator_name} in your kubernetes cluster according to
xref:cloud/operator/install-serverless-operator.adoc[operator installation]
guide.
Use the `deploy` command with kn workflow to deploy the {product_name} project
into your local cluster.
-* Create a namespace for your application
+.Procedure
+. Create a namespace for your application
++
[source,bash]
----
kubectl create namespace my-sf-application
----
-* Deploy to cluster
+. Deploy the workflow to the cluster in the default `dev` mode. The plugin
uses settings located in `./<home>/.kube/config` to access the cluster.
++
[source,bash]
----
kn workflow deploy --namespace my-sf-application
----
-* Using k9s cli you can examine your deployment.
* In a separate bash instance create a port mapping:
+
[tabs]
====
+Openshift::
++
+--
+[source,shell]
+----
+oc get route svc/hello --namespace my-sf-application
+----
+* On openshift the route is generated for you in `dev` mode deployments. Use
the URL of the generated route to access your workflow instances using the
Developement interface.
+** <RETURNED_URL>{sonataflow_devmode_devui_url}workflows
+--
Minikube::
+
--
@@ -93,38 +140,20 @@ kubectl port-forward service/hello <RANDOM_PORT>:80 -n
my-sf-application
--
====
-* To update the image, run the `deploy` again, note that this may take some
time.
-* To stop the deployment, use the `undeploy` command:
+* To update the image, run the `deploy` again, note that this may take some
time. You can also direcly edit the `Sonataflow` resource in the cluster. In
`dev` mode, the operator will update the deployment with the changes.
+. To stop the deployment, use the `undeploy` command:
++
[source,bash]
----
kn workflow undeploy --namespace my-sf-application
----
-* You can validate your pod is terminating using k9s cli.
[[proc-testing-application]]
== Testing your workflow application
-To test your workflow application you can use any capable REST client out
there. All that is needed is the URL of your deployed workflow project.
-
-.Prerequisites
-* You have your workflow project deployed using
<<proc-deploying-app-with-kn-cli>> and you have the URL where it is deployed
handy.
-
-.Testing your workflow application
-* To test your workflow project, access the Swagger UI on `<URL>/q/swagger-ui`
to examine available endpoints.
-* In order to execute the workflow once, run:
-[source,bash]
-----
-curl -X 'POST' \
- '<URL>/hello' \
- -H 'accept: */*' \
- -H 'Content-Type: application/json' \
- -d '{
- "workflowdata": {}
-}'
-----
-* To examine executed instance you can use the GraphQL UI by navigating to
-`<URL>/q/graphl-ui`.
-
+To test your workflow application you can use any capable REST client out
there. All that is needed is the URL of your deployed workflow project, which
is showcase in section above,
+You can also use the management console provided as part of the development
interface.
+Please see the additional resources to proceed.
== Additional resources
diff --git
a/serverlessworkflow/modules/ROOT/pages/getting-started/preparing-environment.adoc
b/serverlessworkflow/modules/ROOT/pages/getting-started/preparing-environment.adoc
index a9f1365c5..906007fbc 100644
---
a/serverlessworkflow/modules/ROOT/pages/getting-started/preparing-environment.adoc
+++
b/serverlessworkflow/modules/ROOT/pages/getting-started/preparing-environment.adoc
@@ -102,6 +102,6 @@ Points listed in this section provide extra possibilities
when working with our
== Additional resources
* xref:getting-started/production-environment.adoc[]
-*
xref:getting-started/create-your-first-workflow-service-with-kn-cli-and-vscode.adoc[]
+* xref:getting-started/introduction-sonataflow-development-guide.adoc[]
include::../../pages/_common-content/report-issue.adoc[]
\ No newline at end of file
diff --git a/serverlessworkflow/modules/ROOT/pages/index.adoc
b/serverlessworkflow/modules/ROOT/pages/index.adoc
index 018176268..c6d15e984 100644
--- a/serverlessworkflow/modules/ROOT/pages/index.adoc
+++ b/serverlessworkflow/modules/ROOT/pages/index.adoc
@@ -49,7 +49,7 @@ Learn about the tools we provide you with, on your journey to
create {product_na
[.card]
--
[.card-title]
-xref:getting-started/create-your-first-workflow-service-with-kn-cli-and-vscode.adoc[]
+xref:getting-started/introduction-sonataflow-development-guide.adoc[]
[.card-description]
An all-in-one starting guide. Learn how to create, run & deploy your first
{product_name} project on your local environment.
--
diff --git
a/serverlessworkflow/modules/ROOT/pages/service-orchestration/orchestration-of-openapi-based-services.adoc
b/serverlessworkflow/modules/ROOT/pages/service-orchestration/orchestration-of-openapi-based-services.adoc
index 19f9f309a..0cda4948b 100644
---
a/serverlessworkflow/modules/ROOT/pages/service-orchestration/orchestration-of-openapi-based-services.adoc
+++
b/serverlessworkflow/modules/ROOT/pages/service-orchestration/orchestration-of-openapi-based-services.adoc
@@ -16,7 +16,7 @@
:mp_config_env_vars_url:
https://github.com/eclipse/microprofile-config/blob/master/spec/src/main/asciidoc/configsources.asciidoc#environment-variables-mapping-rules
// Referenced documentation pages.
:getting-familiar-with-our-tooling:
xref:getting-started/getting-familiar-with-our-tooling.adoc
-:create-your-first-workflow-service:
xref:getting-started/create-your-first-workflow-service-with-kn-cli-and-vscode.adoc
+:create-your-first-workflow-service:
xref:getting-started/introduction-sonataflow-development-guide.adoc
:build-workflow-image-with-quarkus-cli:
xref:use-cases/advanced-developer-use-cases/getting-started/build-workflow-image-with-quarkus-cli.adoc
:understanding-jq-expressions: xref:core/understanding-jq-expressions.adoc
:configuring-openapi-services-endpoints:
xref:service-orchestration/configuring-openapi-services-endpoints.adoc
diff --git
a/serverlessworkflow/modules/ROOT/pages/testing-and-troubleshooting/kn-plugin-workflow-overview.adoc
b/serverlessworkflow/modules/ROOT/pages/testing-and-troubleshooting/kn-plugin-workflow-overview.adoc
index 1c445e5af..1f4607fa3 100644
---
a/serverlessworkflow/modules/ROOT/pages/testing-and-troubleshooting/kn-plugin-workflow-overview.adoc
+++
b/serverlessworkflow/modules/ROOT/pages/testing-and-troubleshooting/kn-plugin-workflow-overview.adoc
@@ -1,4 +1,4 @@
-= {product_name} plug-in for Knative CLI
+= {product_name} plugin for Knative CLI
:compat-mode!:
// Metadata:
@@ -7,28 +7,22 @@
// links
:apple_support_url: https://support.apple.com/guide/mac-help/mh40616/mac
-{product_name} provides a plug-in named `kn-workflow` for Knative CLI, which
provides command line features that help you develop a local workflow project
quickly.
-
-This document describes how you can install and use the `kn-workflow` plug-in
in {product_name}.
+{product_name} provides a workflow plugin for Knative CLI, which provides
command line interface that helps you develop & deploy your workflow projects.
+This document describes how you can work with the {product_name} workflow
plugin.
You can also find brief introduction for some of the commands that the plugin
provides.
[[proc-install-sw-plugin-kn-cli]]
-== Installing the {product_name} plug-in for Knative CLI
+== Installing the {product_name} plugin for Knative CLI
-You can use the {product_name} plug-in to set up your local workflow project
quickly using Knative CLI.
+You can use the {product_name} plugin to set up your local workflow project
quickly using Knative CLI.
.Prerequisites
-* link:{java_install_url}[Java] {java_min_version} is installed.
-* link:{maven_install_url}[Maven] {maven_min_version} or later is installed.
-* (Optional) link:{docker_install_url}[Docker] is installed.
-* (Optional) link:{podman_install_url}[Podman] is installed.
-* link:{kubectl_install_url}[Kubernetes CLI] is installed.
* link:{kn_cli_install_url}[Knative CLI] is installed.
.Procedure
-. Download the latest binary file, suitable for your environment, from the
link:{kie_tools_releases_page_url}[KIE Tooling Releases] page.
-. Install the `kn workflow` command as a plug-in of the Knative CLI using the
following steps:
+. Download the latest binary file, suitable for your environment, from the
Apache KIE link:{kie_tools_releases_page_url}[download] page for releases.
+. Install the `kn workflow` command as a plugin of the Knative CLI using the
following steps:
+
--
.. Rename the downloaded binary as follows:
@@ -41,14 +35,16 @@ mv kn-workflow-linux-amd64 kn-workflow
+
[WARNING]
====
-On Mac, some systems might block the application to run due to Apple enforcing
policies. To fix this problem, check the *Security & Privacy* section in the
*System Preferences* -> *General* tab to approve the application to run. For
more information, see link:{apple_support_url}[Apple support article: Open a
Mac app from an unidentified developer].
+On Mac, some systems might block the application to run due to Apple enforcing
policies. To fix this problem, check the *Security & Privacy* section in the
*System Preferences* -> *General* tab to approve the application to run.
+For more information, see the link:{apple_support_url}[support article from
Apple with more details].
====
.. Copy the `kn-workflow` binary file to `/usr/local/bin`.
-.. Run the following command to verify that `kn-workflow` plug-in is installed
successfully:
+.. Run the following command to verify that `kn-workflow` plugin is installed
successfully:
+
`kn plugin list`
+.. You should see a following line `kn-workflow : /usr/local/bin/kn-workflow`
in the output.
-After installing the plug-in, you can use `kn workflow` to run the related
subcommands.
+After installing the plugin, you can use `kn workflow` to run the related
subcommands.
--
. Use the `workflow` subcommand in Knative CLI as follows:
@@ -61,68 +57,33 @@ kn workflow
kn-workflow
----
-.Example output
-[source,text]
+.Workflow plugin provides bulit-in documentation for each command, display it
by adding `--help` after the command
+[source,terminal]
+----
+$ kn workflow --help
----
- Manage SonataFlow projects
-
- Currently, SonataFlow targets use cases with a single Serverless
Workflow main
- file definition (i.e. workflow.sw.{json|yaml|yml}).
-
- Additionally, you can define the configurable parameters of your
application in the
- "application.properties" file (inside the root project directory).
- You can also store your spec files (i.e., OpenAPI files) inside the
"specs" folder,
- schemas file inside "schemas" folder and also subflows inside "subflows"
folder.
-
- A SonataFlow project, as the following structure by default:
-
- Workflow project root
- /specs (optional)
- /schemas (optional)
- /subflows (optional)
- workflow.sw.{json|yaml|yml} (mandatory)
-
-
-
-Usage:
- kn workflow [command]
-
-Aliases:
- kn workflow, kn-workflow
-
-Available Commands:
- completion Generate the autocompletion script for the specified shell
- create Creates a new SonataFlow project
- deploy Deploy a SonataFlow project on Kubernetes via SonataFlow
Operator
- gen-manifest GenerateOperator manifests
- help Help about any command
- quarkus Manage SonataFlow projects built in Quarkus
- run Run a SonataFlow project in development mode
- undeploy Undeploy a SonataFlow project on Kubernetes via SonataFlow
Operator
- version Show the version
-
-Flags:
- -h, --help help for kn workflow
- -v, --version version for kn workflow
-Use "kn workflow [command] --help" for more information about a command.
+.See the documentation of `run` command
+[source,text]
+----
+$ kn workflow run --help
----
--
[[proc-create-sw-project-kn-cli]]
== Creating a workflow project using Knative CLI
-After installing the {product_name} plug-in, you can use the `create` command
with `kn workflow` to scaffold a new {product_name} project in your current
directory.
+After installing the {product_name} plugin, you can use the `create` command
with `kn workflow` to scaffold a new {product_name} project in your current
directory.
The `create` command sets up {product_name} project containing a minimal
"hello world" `workflow.sw.json` file in your `./<project-name>` directory.
.Prerequisites
-* {product_name} plug-in for Knative CLI is installed.
+* {product_name} plugin for Knative CLI is installed.
+
-For more information about installing the plug-in, see
<<proc-install-sw-plugin-kn-cli, Installing the {product_name} plug-in for
Knative CLI>>.
+For more information about installing the plugin, see
<<proc-install-sw-plugin-kn-cli, Installing the {product_name} plugin for
Knative CLI>>.
.Procedure
-. You can use the following command to create a new project:
+. You can use the following commands to create a new project:
+
--
.Creates a project named `new-project`
@@ -139,27 +100,30 @@ By default, the generated project is named as
`new-project`. You can overwrite t
kn workflow create --name my-project
----
--
-
++
This will scaffold a directory named `my-project` with a simple workflow in
JSON format. You can overwrite the format of the workflow to YAML by using the
`[--yaml-workflow]` flag as follows:
-
++
.Create a project named `my-project` with default workflow in YAML format
[source,shell]
----
kn workflow create --name my-project --yaml-workflow
----
---
+
[[proc-build-sw-project-kn-cli]]
== Running a workflow project using Knative CLI
After creating your workflow project, you can use the `run` command with `kn
workflow` to build & run your workflow project. You must be in the root folder
of your workflow project.
-This plugin will build your project and start a {product_name} container image
that will be mapped to your local folder.
+The plugin will build your project and start a {product_name} container image
in your configured container runtime, that will be mapped to your local folder.
A development UI with management console
+is provided for your to test your workflows functionality.
.Prerequisites
-* {product_name} plug-in for Knative CLI is installed.
+* {product_name} plugin for Knative CLI is installed.
+
-For more information about installing the plug-in, see
<<proc-install-sw-plugin-kn-cli, Installing the {product_name} plug-in for
Knative CLI>>.
+For more information about installing the plugin, see
<<proc-install-sw-plugin-kn-cli, Installing the {product_name} plugin for
Knative CLI>>.
+
+* You have set up your environment according to the
xref:getting-started/preparing-environment.adoc#proc-minimal-local-environment-setup[minimal
environment setup] guide.
* A workflow project is created.
+
@@ -186,7 +150,9 @@ By default, the development image is using port `8080`. You
can map it to a diff
----
kn workflow run --port 8081
----
---
+
+
+For more options with `run` command use `[-h|--help]`.
[[proc-gen-manifests-sw-project-kn-cli]]
== Generating a list of Operator manifests using Knative CLI
@@ -196,9 +162,9 @@ After creating your workflow project, you can use the
`gen-manifest` command wit
This will screate a new file in `./manifests` directory in your project.
.Prerequisites
-* {product_name} plug-in for Knative CLI is installed.
+* {product_name} plugin for Knative CLI is installed.
+
-For more information about installing the plug-in, see
<<proc-install-sw-plugin-kn-cli, Installing the {product_name} plug-in for
Knative CLI>>.
+For more information about installing the plugin, see
<<proc-install-sw-plugin-kn-cli, Installing the {product_name} plugin for
Knative CLI>>.
* A workflow project is created.
+
@@ -235,9 +201,9 @@ For more options with `gen-manifest` command use
`[-h|--help]`.
You can use the `deploy` command combined with `kn workflow` to deploy your
workflow project. You must be in the root folder of your workflow project.
.Prerequisites
-* {product_name} plug-in for Knative CLI is installed.
+* {product_name} plugin for Knative CLI is installed.
+
-For more information about installing the plug-in, see
<<proc-install-sw-plugin-kn-cli, Installing the {product_name} plug-in for
Knative CLI>>.
+For more information about installing the plugin, see
<<proc-install-sw-plugin-kn-cli, Installing the {product_name} plugin for
Knative CLI>>.
* A workflow project is created.
+
@@ -245,6 +211,8 @@ For more information about creating a workflow project, see
<<proc-create-sw-pro
* You have set up your environment according to the
xref:getting-started/preparing-environment.adoc#proc-minimal-local-environment-setup[minimal
environment setup] guide.
+* You are logged into your kubernetes cluster or started one locally according
to the
xref:getting-started/preparing-environment.adoc#proc-starting-cluster-fo-local-development[starting
cluster for local development] guide.
+
* You have installed {operator_name} in your kubernetes cluster according to
xref:cloud/operator/install-serverless-operator.adoc[operator installation]
guide.
.Procedure
@@ -266,16 +234,46 @@ You can use the `kubectl` command line if you want to use
a complex deployment s
====
--
+For more options with `deploy` command use `[-h|--help]`.
+
+[[proc-undeploy-sw-project-kn-cli]]
+== Undeploying a workflow project using Knative CLI
+
+You can use the `undeploy` command combined with `kn workflow` to undeploy
your workflow project. You must be in the root folder of your workflow project.
+
+.Prerequisites
+* {product_name} plugin for Knative CLI is installed.
++
+For more information about installing the plugin, see
<<proc-install-sw-plugin-kn-cli, Installing the {product_name} plugin for
Knative CLI>>.
+
+* A workflow project is deplyed in your cluster.
++
+For more information about creating a workflow project, see
<<proc-create-sw-project-kn-cli, Creating workflow project using Knative CLI>>.
+
+.Procedure
+. Enter the following command to deploy your workflow project:
++
+--
+.Undeploy a workflow project, you must specify a namespace
+[source,shell]
+----
+kn workflow undeploy --namespace <your_namespace>
+----
+--
+
+For more options with `undeploy` command use `[-h|--help]`.
+
[[proc-create-quarkus-sw-project-kn-cli]]
== Creating a Quarkus Workflow project using Knative CLI
-After installing the {product_name} plug-in, you can use the `quarkus create`
command with `kn workflow` to scaffold a new Quarkus Workflow project in your
current directory.
+After installing the {product_name} plugin, you can use the `quarkus create`
command with `kn workflow` to scaffold a new Quarkus Workflow project in your
current directory.
The `quarkus create` command sets up a {product_name} Quarkus project
containing minimal extensions to build a workflow project. Also, the generated
workflow project contains a "hello world" `workflow.sw.json` file in your
`./<project-name>/src/main/resources` directory.
.Prerequisites
-* {product_name} plug-in for Knative CLI is installed.
-For more information about installing the plug-in, see
<<proc-install-sw-plugin-kn-cli, Installing the {product_name} plug-in for
Knative CLI>>.
+* {product_name} plugin for Knative CLI is installed.
+For more information about installing the plugin, see
<<proc-install-sw-plugin-kn-cli, Installing the {product_name} plugin for
Knative CLI>>.
+* You have set up your environment according to the
xref:getting-started/preparing-environment.adoc#proc-advanced-local-environment-setup[advanced
environment setup] guide.
ifeval::["{kogito_version_redhat}" != ""]
* You followed the steps in
xref:use-cases/advanced-developer-use-cases/getting-started/create-your-first-workflow-service.adoc#proc-configuring-maven-rhbq[Configuring
your Maven project to Red Hat build of Quarkus and OpenShift Serverless Logic]
endif::[]
@@ -324,10 +322,10 @@ After creating your workflow project, you can use the
`quarkus build` command wi
The process of building your workflow project produces a `knative.yml` file in
the `./target/kubernetes` folder. If your workflow contains events, then the
building process also generates a `kogito.yml` file.
.Prerequisites
-* {product_name} plug-in for Knative CLI is installed.
+* {product_name} plugin for Knative CLI is installed.
+
-For more information about installing the plug-in, see
<<proc-install-sw-plugin-kn-cli, Installing the {product_name} plug-in for
Knative CLI>>.
-
+For more information about installing the plugin, see
<<proc-install-sw-plugin-kn-cli, Installing the {product_name} plugin for
Knative CLI>>.
+* You have set up your environment according to the
xref:getting-started/preparing-environment.adoc#proc-advanced-local-environment-setup[advanced
environment setup] guide.
* A workflow project is created.
+
For more information about creating a workflow project, see
<<proc-create-sw-project-kn-cli, Creating workflow project using Knative CLI>>.
@@ -439,9 +437,9 @@ For more options with `quarkus build` command use
`[-h|--help]`.
You can use the `quarkus deploy` command combined with `kn workflow` to deploy
your workflow project in your current directory. However, before deploying the
project, you must build your workflow project as the build process produces
deployment files, such as `knative.yml` and `kogito.yml` (In case of events) in
the `./target/kubernetes` folder.
.Prerequisites
-* {product_name} plug-in for Knative CLI is installed.
+* {product_name} plugin for Knative CLI is installed.
+
-For more information about installing the plug-in, see
<<proc-install-sw-plugin-kn-cli, Installing the {product_name} plug-in for
Knative CLI>>.
+For more information about installing the plugin, see
<<proc-install-sw-plugin-kn-cli, Installing the {product_name} plugin for
Knative CLI>>.
* A workflow project is created.
+
@@ -451,7 +449,11 @@ For more information about created a workflow project, see
<<proc-create-sw-proj
+
For more information about building your workflow project, see
<<proc-build-sw-project-kn-cli, Building workflow project using Knative CLI>>.
-* You have set up your environment according to the
xref:getting-started/preparing-environment.adoc#proc-minimal-local-environment-setup[minimal
environment setup] guide.
+* You have set up your environment according to the
xref:getting-started/preparing-environment.adoc#proc-advanced-local-environment-setup[advanced
environment setup] guide.
+
+* You are logged into your kubernetes cluster or started one locally according
to the
xref:getting-started/preparing-environment.adoc#proc-starting-cluster-fo-local-development[starting
cluster for local development] guide.
+
+* You have installed {operator_name} in your kubernetes cluster according to
xref:cloud/operator/install-serverless-operator.adoc[operator installation]
guide.
.Procedure
. Enter the following command to deploy your workflow project:
@@ -475,14 +477,16 @@ Also, ensure that you have access to your cluster and
your cluster can access th
[NOTE]
====
-You can use the `kubectl` command line if you want to use a complex deployment
setup for your workflow project.
+You can use the `kubectl` or other command line tools if you want to use a
complex deployment setup for your workflow project.
====
--
+For more options with `quarkus deploy` command use `[-h|--help]`.
+
== Additional resources
-*
xref:getting-started/create-your-first-workflow-service-with-kn-cli-and-vscode.adoc[Creating
your first SonataFlow project]
+* xref:getting-started/introduction-sonataflow-development-guide.adoc[Creating
your first SonataFlow project]
*
xref:use-cases/advanced-developer-use-cases/getting-started/create-your-first-workflow-service.adoc[Creating
your first SonataFlow project with Quarkus]
include::../../pages/_common-content/report-issue.adoc[]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
