diff --git a/serverlessworkflow/antora.yml b/serverlessworkflow/antora.yml index 5eaa9b829..c856c7f0e 100644 --- a/serverlessworkflow/antora.yml +++ b/serverlessworkflow/antora.yml @@ -5,6 +5,7 @@ display_version: snapshot prerelease: snapshot start_page: index.adoc nav: +- "modules/ROOT/pages/getting-started/nav.adoc" - "modules/ROOT/nav.adoc" asciidoc: attributes: diff --git a/serverlessworkflow/modules/ROOT/nav.adoc b/serverlessworkflow/modules/ROOT/nav.adoc index f5c3988c6..6a452c24a 100644 --- a/serverlessworkflow/modules/ROOT/nav.adoc +++ b/serverlessworkflow/modules/ROOT/nav.adoc @@ -1,9 +1,5 @@ // * xref:index.adoc[Home] * xref:release_notes.adoc[Release notes for {context}] -* Getting Started -** xref:getting-started/create-your-first-workflow-service.adoc[Creating your first workflow service] -** xref:getting-started/cncf-serverless-workflow-specification-support.adoc[CNCF Serverless Workflow specification] -** xref:getting-started/getting-familiar-with-our-tooling.adoc[Getting familiar with {context} tooling] * Core ** xref:core/understanding-jq-expressions.adoc[jq expressions in {context}] ** xref:core/understanding-workflow-error-handling.adoc[Error handling in {context}] 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 37a3a97b6..d7c10b4d1 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.adoc[Creating your first Serverless Workflow service]. \ No newline at end of file +For more information about creating a workflow project, see xref:getting-started/modules/create-your-first-workflow-service.adoc[Creating your first Serverless Workflow service]. diff --git a/serverlessworkflow/modules/ROOT/pages/getting-started/create-your-first-workflow-service.adoc b/serverlessworkflow/modules/ROOT/pages/getting-started/create-your-first-workflow-service.adoc deleted file mode 100644 index 0cac7364e..000000000 --- a/serverlessworkflow/modules/ROOT/pages/getting-started/create-your-first-workflow-service.adoc +++ /dev/null @@ -1,373 +0,0 @@ -= Creating your first workflow service - -As a developer, you can use {context} and create a `Hello World` application, which includes the following procedures: - -* <> -* <> -* <> -* <> - -Also, you can directly access an example application by cloning `serverless-workflow-examples/serverless-workflow-hello-world` from the link:{kogito_sw_examples_url}/serverless-workflow-hello-world[GitHub repository]. - -This document describes how to create a workflow application that serves a `hello_world` endpoint. The workflow contains the following two states: - -* `Inject Hello World`: Injects a `Hello World` message into the response -* `Inject Mantra`: Injects a `Mantra` message into the response - -.Example Hello World workflow -image::getting-started/hello-world-workflow.png[] - -.Prerequisites -* Java {java_min_version} is installed with `JAVA_HOME` configured appropriately. -* Apache Maven {maven_min_version} is installed. -* {quarkus_cli_url}[Quarkus CLI] or xref:tooling/kn-plugin-workflow-overview.adoc[Knative Workflow CLI] {kn_cli_version} is installed. -* Visual Studio Code with https://marketplace.visualstudio.com/items?itemName=redhat.java[Red Hat Java Extension] -and https://marketplace.visualstudio.com/items?itemName=redhat.vscode-extension-serverless-workflow-editor[Red Hat Serverless Workflow Editor] is installed to edit your workflows. - -For more information about the tooling and the required dependencies, see xref:getting-started/getting-familiar-with-our-tooling.adoc[Getting familiar with {context} tooling]. - -ifeval::["{kogito_version_redhat}" != ""] -include::../../pages/_common-content/downstream-project-setup-instructions.adoc[] -endif::[] - -[[proc-boostrapping-the-project]] -== Bootstrapping a project - -To create your workflow service, first you need to bootstrap a project. - -.Procedure -. In a command terminal, use one of the following commands to create a project: -+ -[tabs] -==== -Quarkus CLI:: -+ --- -.Create a project using Quarkus CLI -[source,shell,subs="attributes+"] ----- -quarkus create app \ - -x={kogito_sw_ga} \ - -x=quarkus-container-image-jib \ - -x=quarkus-resteasy-jackson \ - -x=quarkus-smallrye-openapi \ - --no-code \ - org.acme:serverless-workflow-hello-world:1.0.0-SNAPSHOT ----- - -The previous command creates a Maven Quarkus project in the `serverless-workflow-hello-world` directory containing the required dependencies, including: - -* `{kogito_sw_ga}`: Adds support for workflows. -* `quarkus-container-image-jib`: Adds support for Container Image Builds. -* `quarkus-resteasy-jackson`: Adds support for RESTEasy, which is required by the generated REST resources that are used to start the flow process using an HTTP request. -* `quarkus-smallrye-openapi`: Adds support for Swagger documentation when you run the application in development mode. -* `--no-code`: Prevents workflow example code from being generated. - -The SwaggerUI is available at `http://localhost:8080/q/swagger-ui/` when you run the application. --- -Apache Maven:: -+ --- -.Create a project using Apache Maven -[source,shell,subs="attributes"] ----- -mvn {quarkus_platform}:quarkus-maven-plugin:{quarkus_version}:create \ - -DprojectGroupId=org.acme \ - -DprojectArtifactId=serverless-workflow-hello-world \ - -Dextensions="{kogito_sw_ga},quarkus-container-image-jib,quarkus-resteasy-jackson,quarkus-smallrye-openapi" \ - -DnoCode -cd serverless-workflow-hello-world ----- - -In the previous command, `org.acme`, `serverless-workflow-hello-world`, and `1.0.0-SNAPSHOT` is group ID, artifact ID, and version of your project respectively. `-DnoCode` prevents the generation of workflow example code. --- -Knative workflow CLI:: -+ --- -.Create a project using Knative workflow CLI - -[source,shell,subs="attributes"] ----- -kn workflow create \ - --name serverless-workflow-hello-world \ - --extension quarkus-jsonp,quarkus-smallrye-openapi \ - --quarkus-platform-group-id={quarkus_platform} \ - --quarkus-version={quarkus_version} ----- - -For more information about Knative workflow CLI, see xref:tooling/kn-plugin-workflow-overview.adoc[{context} plug-in for Knative CLI]. --- -==== - -[[proc-creating-workflow]] -== Creating a workflow - -After bootstrapping a project, you need to create a workflow. In the following procedure, a workflow named *Hello World Workflow* is created. - -.Procedure -. Create a file named `hello.sw.json` in the `src/main/resources` directory with the following content: -+ --- -.Example content for `hello.sw.json` file -[source,json] ----- -{ - "id": "hello_world", <1> - "version": "1.0", - "specVersion": "0.8", - "name": "Hello World Workflow", - "description": "JSON based hello world workflow", - "start": "Inject Hello World", <3> - "states": [ <2> - { - "name": "Inject Hello World", - "type": "inject", <4> - "data": { <5> - "greeting": "Hello World" - }, - "transition": "Inject Mantra" <6> - }, - { - "name": "Inject Mantra", - "type": "inject", - "data": { - "mantra": "Serverless Workflow is awesome!" <7> - }, - "end": true <8> - } - ] -} ----- -In the previous example: - -<1> `id` field is the unique identifier of the workflow. {product_name} generates the REST endpoints based on this unique identifier. - -<2> `states` defines the states of the workflow. In the Hello World example, the workflow contains two states, such as `Inject Hello World` and `Inject Mantra`. - -<3> `start` field defines the state in which the workflow starts. - -<4> `type` defines the type of the state. In the previous example, the state is `inject`. The `inject` state can be used to inject static data into state data input. - -<5> `data` defines the data that is injected into the state. In the previous example, `greeting` is injected with the `Hello World` value. - -<6> `transition` field defines the next state that is reached after the current state is completed. - -<7> Injects a `mantra` with the value `Serverless Workflow is awesome!` into the workflow data. - -<8> `end` field defines that the current state is the end of the workflow. When the workflow reaches the end state, the workflow stops and the REST endpoint returns the workflow data, such as: - -.Example workflow data -[source,json] ----- -{ - "greeting": "Hello World", - "mantra": "Serverless Workflow is awesome!" -} ----- - -[NOTE] -==== -The workflow definition follows the CNCF Serverless Workflow specification. For more information, see -xref:getting-started/cncf-serverless-workflow-specification-support.adoc[CNCF Serverless Workflow specification]. -==== --- - -[[proc-building-application]] -== Building your workflow application - -ifeval::["{kogito_version_redhat}" != ""] -include::../../pages/_common-content/downstream-post-create-project.adoc[] -endif::[] - -. To verify that project is created, compile the project using the following command: -+ -[tabs] -==== -Quarkus CLI:: -+ --- -.Compile your project using Quarkus CLI -[source,shell] ----- -quarkus build ----- --- -Apache Maven:: -+ --- -.Compile your project using Apache Maven -[source,shell] ----- -mvn clean package ----- --- -Knative workflow CLI:: -+ --- -.Build your project and generate a local image called `dev.local/serverless-workflow-hello-world:latest` -[source,shell] ----- -kn workflow build --image dev.local/serverless-workflow-hello-world --verbose ----- -The `--verbose` flag is used to display the output of the build command. This flag is optional. - -For more information about Knative workflow CLI, see xref:tooling/kn-plugin-workflow-overview.adoc[{context} plug-in for Knative CLI]. --- -==== - -[[proc-running-application]] -== Running your workflow application - -After creating a workflow, you can run your workflow application. - -.Procedure -. Enter the following command to run your workflow application: -+ - -[tabs] -==== -Quarkus CLI:: -+ --- -.Run your workflow application using Quarkus CLI -[source,shell] ----- -quarkus dev ----- --- -Apache Maven:: -+ --- -.Run your workflow application using Apache Maven -[source,shell] ----- -mvn clean quarkus:dev ----- --- -Knative workflow CLI: -+ --- -Currently, Knative workflow CLI doesn't support yet running workflows locally. You can either: - -.Run your workflow application using Apache Maven -[source,shell] ----- -mvn clean quarkus:dev ----- - -.Run your workflow application using Quarkus CLI -[source,shell] ----- -quarkus dev ----- - -For more information about Knative workflow CLI, see xref:tooling/kn-plugin-workflow-overview.adoc[{context} plug-in for Knative CLI]. - -Also, to deploy and run your workflow application, see xref:cloud/deploying-on-minikube.adoc[Deploying workflow application on Minikube] --- -==== -+ -.Example response -[source,shell,subs="attributes"] ----- -[INFO] ------< org.acme:serverless-workflow-hello-world >------- -[INFO] Building serverless-workflow-hello-world 1.0.0-SNAPSHOT -[INFO] --------------------------------[ jar ]--------------------------------- -[INFO] -[INFO] --- quarkus-maven-plugin:{quarkus_version}:dev (default-cli) @ serverless-workflow-hello-world --- -[INFO] Invoking org.apache.maven.plugins:maven-resources-plugin:2.6:resources) @ serverless-workflow-hello-world -[INFO] Using 'UTF-8' encoding to copy filtered resources. -[INFO] Copying 3 resources -...more output... -__ ____ __ _____ ___ __ ____ ______ - --/ __ \/ / / / _ | / _ \/ //_/ / / / __/ - -/ /_/ / /_/ / __ |/ , _/ ,< / /_/ /\ \ ---\___\_\____/_/ |_/_/|_/_/|_|\____/___/ -2022-05-25 14:38:09,741 INFO [org.kie.kog.add.qua.mes.com.QuarkusKogitoExtensionInitializer] (Quarkus Main Thread) Registered Kogito CloudEvent extension -2022-05-25 14:38:09,840 INFO [io.quarkus] (Quarkus Main Thread) serverless-workflow-hello-world 1.0.0-SNAPSHOT on JVM (powered by Quarkus {quarkus_version}) started in 6.470s. Listening on: http://localhost:8080 -2022-05-25 14:38:09,843 INFO [io.quarkus] (Quarkus Main Thread) Profile dev activated. Live Coding activated. -2022-05-25 14:38:09,843 INFO [io.quarkus] (Quarkus Main Thread) Installed features: [cache, cdi, jackson-jq, kogito-addon-messaging-extension, kogito-processes, kogito-serverless-workflow, reactive-routes, rest-client, rest-client-jackson, resteasy, resteasy-jackson, smallrye-context-propagation, smallrye-openapi, smallrye-reactive-messaging, smallrye-reactive-messaging-http, swagger-ui, vertx] -2022-05-25 14:38:12,877 INFO [org.kie.kog.qua.pro.dev.DataIndexInMemoryContainer] (docker-java-stream--938264210) STDOUT: __ ____ __ _____ ___ __ ____ ______ -2022-05-25 14:38:12,878 INFO [org.kie.kog.qua.pro.dev.DataIndexInMemoryContainer] (docker-java-stream--938264210) STDOUT: --/ __ \/ / / / _ | / _ \/ //_/ / / / __/ -2022-05-25 14:38:12,879 INFO [org.kie.kog.qua.pro.dev.DataIndexInMemoryContainer] (docker-java-stream--938264210) STDOUT: -/ /_/ / /_/ / __ |/ , _/ ,< / /_/ /\ \ -2022-05-25 14:38:12,879 INFO [org.kie.kog.qua.pro.dev.DataIndexInMemoryContainer] (docker-java-stream--938264210) STDOUT: --\___\_\____/_/ |_/_/|_/_/|_|\____/___/ -2022-05-25 14:38:12,879 INFO [org.kie.kog.qua.pro.dev.DataIndexInMemoryContainer] (docker-java-stream--938264210) STDOUT: 2022-05-25 17:38:09,692 INFO [io.zon.tes.db.pos.emb.EmbeddedPostgres] (main) Detected a Linux x86_64 system -2022-05-25 14:38:12,880 INFO [org.kie.kog.qua.pro.dev.DataIndexInMemoryContainer] (docker-java-stream--938264210) STDOUT: 2022-05-25 17:38:09,705 INFO [io.zon.tes.db.pos.emb.DefaultPostgresBinaryResolver] (main) Detected distribution: 'Red Hat Enterprise Linux' -...more output... -2022-05-25 14:38:12,889 INFO [org.kie.kog.qua.pro.dev.DataIndexInMemoryContainer] (docker-java-stream--938264210) STDOUT: 2022-05-25 17:38:12,332 INFO [io.zon.tes.db.pos.emb.EmbeddedPostgres] (postgres:pid(90)) 2022-05-25 17:38:12.332 UTC [99] LOG: incomplete startup packet -2022-05-25 14:38:12,890 INFO [org.kie.kog.qua.pro.dev.DataIndexInMemoryContainer] (docker-java-stream--938264210) STDOUT: 2022-05-25 17:38:12,405 INFO [io.zon.tes.db.pos.emb.EmbeddedPostgres] (main) 5df1ed6e-7a15-4091-bcfb-e293aa293bfe postmaster startup finished in 00:00:00.180 -2022-05-25 14:38:12,890 INFO [org.kie.kog.qua.pro.dev.DataIndexInMemoryContainer] (docker-java-stream--938264210) STDOUT: 2022-05-25 17:38:12,405 INFO [org.kie.kog.per.inm.pos.run.InmemoryPostgreSQLRecorder] (main) Embedded Postgres started at port "44729" with database "postgres", user "postgres" and password "postgres" -2022-05-25 14:38:12,890 INFO [org.kie.kog.qua.pro.dev.DataIndexInMemoryContainer] (docker-java-stream--938264210) STDOUT: 2022-05-25 17:38:12,636 WARN [io.qua.run.con.ConfigRecorder] (main) Build time property cannot be changed at runtime: -2022-05-25 14:38:12,891 INFO [org.kie.kog.qua.pro.dev.DataIndexInMemoryContainer] (docker-java-stream--938264210) STDOUT: - quarkus.jib.base-jvm-image is set to 'ba-docker-registry.usersys.redhat.com:5000/fabric8/java-alpine-openjdk11-jre' but it is build time fixed to 'fabric8/java-alpine-openjdk11-jre'. Did you change the property quarkus.jib.base-jvm-image after building the application? -2022-05-25 14:38:13,375 INFO [org.kie.kog.qua.pro.dev.DataIndexInMemoryContainer] (docker-java-stream--938264210) STDOUT: 2022-05-25 17:38:13,105 INFO [org.kie.kog.per.pro.ProtobufService] (main) Registering Kogito ProtoBuffer file: kogito-index.proto -2022-05-25 14:38:13,377 INFO [org.kie.kog.qua.pro.dev.DataIndexInMemoryContainer] (docker-java-stream--938264210) STDOUT: 2022-05-25 17:38:13,132 INFO [org.kie.kog.per.pro.ProtobufService] (main) Registering Kogito ProtoBuffer file: kogito-types.proto -2022-05-25 14:38:13,378 INFO [org.kie.kog.qua.pro.dev.DataIndexInMemoryContainer] (docker-java-stream--938264210) STDOUT: 2022-05-25 17:38:13,181 INFO [io.quarkus] (main) data-index-service-inmemory 1.22.0.Final on JVM (powered by Quarkus 2.9.0.Final) started in 4.691s. Listening on: http://0.0.0.0:8080 -2022-05-25 14:38:13,379 INFO [org.kie.kog.qua.pro.dev.DataIndexInMemoryContainer] (docker-java-stream--938264210) STDOUT: 2022-05-25 17:38:13,182 INFO [io.quarkus] (main) Profile prod activated. -2022-05-25 14:38:13,380 INFO [org.kie.kog.qua.pro.dev.DataIndexInMemoryContainer] (docker-java-stream--938264210) STDOUT: 2022-05-25 17:38:13,182 INFO [io.quarkus] (main) Installed features: [agroal, cdi, hibernate-orm, hibernate-orm-panache, inmemory-postgres, jdbc-postgresql, narayana-jta, oidc, reactive-routes, rest-client-reactive, rest-client-reactive-jackson, security, smallrye-context-propagation, smallrye-graphql-client, smallrye-health, smallrye-metrics, smallrye-reactive-messaging, smallrye-reactive-messaging-http, vertx, vertx-graphql] ----- - -. Once your workflow application is started, you can send a request for the provided endpoint: -+ - -+ -.Example request -[source,shell] ----- -curl -X POST -H 'Content-Type:application/json' http://localhost:8080/hello_world ----- - -+ --- -.Example response -[source,shell] ----- -{"id":"efb59bfa-ad9c-4062-a6d2-2d9184dd4b3d","workflowdata":{"greeting":"Hello World","mantra":"Serverless Workflow is awesome!"}} ----- --- - -. When running in development mode (using Quarkus CLI or Apache Maven), you can update your workflow with a new `mantra` value without restarting the application. -+ --- -.Update your workflow -[source,json] ----- -{ - "name": "Inject Mantra", - "type": "inject", - "data": { - "mantra": "Serverless Workflow is amazing!" <1> - }, - "end": true -} ----- -<1> New `mantra` value - -.Example request -[source,shell] ----- -curl -X POST -H 'Content-Type:application/json' http://localhost:8080/hello_world ----- - -.Example response -[source,shell] ----- -{"id":"efb59bfa-ad9c-4062-a6d2-2d9184dd4b3d","workflowdata":{"greeting":"Hello World","mantra":"Serverless Workflow is amazing!"}} ----- - -Note that the `mantra` value is updated without restarting the application, because {product_name} leverages the Quarkus live coding feature. --- - -. To stop the application, press `CTRL+C`. - -[[proc-testing-application]] -== Testing your workflow application - -To test your workflow application, you can follow the instructions in the -xref:testing-and-troubleshooting/basic-integration-tests-with-restassured.adoc[Testing your workflow application using REST Assured]. - -== Additional resources - -* xref:getting-started/getting-familiar-with-our-tooling.adoc[Getting familiar with {context} tooling] -* xref:service-orchestration/orchestration-of-openapi-based-services.adoc[Orchestrating the OpenAPI services] - -include::../../pages/_common-content/report-issue.adoc[] diff --git a/serverlessworkflow/modules/ROOT/pages/getting-started/images/first-workflow/hello-world-workflow.png b/serverlessworkflow/modules/ROOT/pages/getting-started/images/first-workflow/hello-world-workflow.png new file mode 100644 index 000000000..e31fd3ca9 Binary files /dev/null and b/serverlessworkflow/modules/ROOT/pages/getting-started/images/first-workflow/hello-world-workflow.png differ diff --git a/serverlessworkflow/modules/ROOT/pages/getting-started/modules/create-your-first-workflow-service.adoc b/serverlessworkflow/modules/ROOT/pages/getting-started/modules/create-your-first-workflow-service.adoc new file mode 100644 index 000000000..c0b4b65fa --- /dev/null +++ b/serverlessworkflow/modules/ROOT/pages/getting-started/modules/create-your-first-workflow-service.adoc @@ -0,0 +1,52 @@ +:_content-type: ASSEMBLY +:description: Creating first workflow service +:keywords: creating, serverless, workflow +:navtitle: Creating your first workflow service +:page-aliases: + +[id="create-your-first-workflow-service_{context}"] += Creating your first workflow service + +As a developer, you can use {context} and create a `Hello World` application, which includes the following procedures: + +* xref:getting-started/modules/proc-boostrapping-the-project.adoc[Bootstrapping a project] +* xref:getting-started/modules/proc-creating-workflow.adoc[Creating a workflow] +* xref:getting-started/modules/proc-running-application.adoc[Running your workflow application] +* xref:getting-started/modules/proc-testing-application.adoc[Testing your workflow application] + +Also, you can directly access an example application by cloning `serverless-workflow-examples/serverless-workflow-hello-world` from the link:{kogito_sw_examples_url}/serverless-workflow-hello-world[GitHub repository]. + +This document describes how to create a workflow application that serves a `hello_world` endpoint. The workflow contains the following two states: + +* `Inject Hello World`: Injects a `Hello World` message into the response +* `Inject Mantra`: Injects a `Mantra` message into the response + +.Example Hello World workflow +image::../../getting-started/images/first-workflow/hello-world-workflow.png[] + +.Prerequisites +* Java {java_min_version} is installed with `JAVA_HOME` configured appropriately. +* Apache Maven {maven_min_version} is installed. +* {quarkus_cli_url}[Quarkus CLI] or xref:tooling/kn-plugin-workflow-overview.adoc[Knative Workflow CLI] {kn_cli_version} is installed. +* Visual Studio Code with https://marketplace.visualstudio.com/items?itemName=redhat.java[Red Hat Java Extension] +and https://marketplace.visualstudio.com/items?itemName=redhat.vscode-extension-serverless-workflow-editor[Red Hat Serverless Workflow Editor] is installed to edit your workflows. + +For more information about the tooling and the required dependencies, see xref:getting-started/getting-familiar-with-our-tooling.adoc[Getting familiar with {context} tooling]. + +ifeval::["{kogito_version_redhat}" != ""] +include::../../../pages/_common-content/downstream-project-setup-instructions.adoc[] +endif::[] + +include::proc-boostrapping-the-project.adoc[leveloffset=+1] +include::proc-creating-workflow.adoc[leveloffset=+1] +include::proc-building-application.adoc[leveloffset=+1] +include::proc-running-application.adoc[leveloffset=+1] +include::proc-testing-application.adoc[leveloffset=+1] + + +.Additional resources + +* xref:getting-started/getting-familiar-with-our-tooling.adoc[Getting familiar with {context} tooling] +* xref:service-orchestration/orchestration-of-openapi-based-services.adoc[Orchestrating the OpenAPI services] + +include::../../../pages/_common-content/report-issue.adoc[] diff --git a/serverlessworkflow/modules/ROOT/pages/getting-started/modules/proc-boostrapping-the-project.adoc b/serverlessworkflow/modules/ROOT/pages/getting-started/modules/proc-boostrapping-the-project.adoc new file mode 100644 index 000000000..2e8a5677a --- /dev/null +++ b/serverlessworkflow/modules/ROOT/pages/getting-started/modules/proc-boostrapping-the-project.adoc @@ -0,0 +1,68 @@ +:_content-type: PROCEDURE +:description: Bootstrapping a project +:keywords: bootstrap, project, serverless, workflow +:navtitle: Bootstrapping a project +// :page-aliases: + +[id="proc-boostrapping-the-project_{context}"] += Bootstrapping a project + +To create your workflow service, first you need to bootstrap a project. + +.Procedure +. In a command terminal, use one of the following commands to create a project: ++ +[tabs] +==== +Quarkus CLI:: ++ +-- +.Create a project using Quarkus CLI +[source,shell,subs="attributes+"] +---- +quarkus create app \ + -x={kogito_sw_ga} \ + -x=quarkus-container-image-jib \ + -x=quarkus-resteasy-jackson \ + -x=quarkus-smallrye-openapi \ + --no-code \ + org.kie.kogito.examples:serverless-workflow-hello-world:1.0 +---- +The previous command creates a Maven Quarkus project in the `serverless-workflow-hello-world` directory containing the required dependencies, including: +* `{kogito_sw_ga}`: Adds support for workflows. +* `quarkus-container-image-jib`: Adds support for Container Image Builds. +* `quarkus-resteasy-jackson`: Adds support for RESTEasy, which is required by the generated REST resources that are used to start the flow process using an HTTP request. +* `quarkus-smallrye-openapi`: Adds support for Swagger documentation when you run the application in development mode. +* `--no-code`: Prevents workflow example code from being generated. +The SwaggerUI is available at `http://localhost:8080/q/swagger-ui/` when you run the application. +-- +Apache Maven:: ++ +-- +.Create a project using Apache Maven +[source,shell,subs="attributes"] +---- +mvn {quarkus_platform}:quarkus-maven-plugin:{quarkus_version}:create \ + -DprojectGroupId=org.kie.kogito.examples \ + -DprojectArtifactId=serverless-workflow-hello-world \ + -Dextensions="{kogito_sw_ga},quarkus-container-image-jib,quarkus-resteasy-jackson,quarkus-smallrye-openapi" \ + -DnoCode +cd serverless-workflow-hello-world +---- +In the previous command, `org.kie.kogito.examples`, `serverless-workflow-hello-world`, and `1.0` is group ID, artifact ID, and version of your project respectively. `-DnoCode` prevents the generation of workflow example code. +-- +Knative workflow CLI:: ++ +-- +.Create a project using Knative workflow CLI +[source,shell,subs="attributes"] +---- +kn workflow create \ + --name serverless-workflow-hello-world \ + --extension quarkus-jsonp,quarkus-smallrye-openapi \ + --quarkus-platform-group-id={quarkus_platform} \ + --quarkus-version={quarkus_version} +---- +For more information about Knative workflow CLI, see xref:tooling/kn-plugin-workflow-overview.adoc[{context} plug-in for Knative CLI]. +-- +==== diff --git a/serverlessworkflow/modules/ROOT/pages/getting-started/modules/proc-building-application.adoc b/serverlessworkflow/modules/ROOT/pages/getting-started/modules/proc-building-application.adoc new file mode 100644 index 000000000..7151ad092 --- /dev/null +++ b/serverlessworkflow/modules/ROOT/pages/getting-started/modules/proc-building-application.adoc @@ -0,0 +1,47 @@ +:_content-type: PROCEDURE +:description: Building your workflow application +:keywords: build, serverless, workflow, application +:navtitle: Building your workflow application +// :page-aliases: + +[id="proc-building-application_{context}"] += Building your workflow application + +ifeval::["{kogito_version_redhat}" != ""] +include::../../pages/_common-content/downstream-post-create-project.adoc[] +endif::[] + +. To verify that project is created, compile the project using the following command: ++ +[tabs] +==== +Quarkus CLI:: ++ +-- +.Compile your project using Quarkus CLI +[source,shell] +---- +quarkus build +---- +-- +Apache Maven:: ++ +-- +.Compile your project using Apache Maven +[source,shell] +---- +mvn clean package +---- +-- +Knative workflow CLI:: ++ +-- +.Build your project and generate a local image called `dev.local/serverless-workflow-hello-world:latest` +[source,shell] +---- +kn workflow build --image dev.local/serverless-workflow-hello-world --verbose +---- +The `--verbose` flag is used to display the output of the build command. This flag is optional. +For more information about Knative workflow CLI, see xref:tooling/kn-plugin-workflow-overview.adoc[{context} plug-in for Knative CLI]. +-- +==== diff --git a/serverlessworkflow/modules/ROOT/pages/getting-started/modules/proc-creating-workflow.adoc b/serverlessworkflow/modules/ROOT/pages/getting-started/modules/proc-creating-workflow.adoc new file mode 100644 index 000000000..4d50ae8e7 --- /dev/null +++ b/serverlessworkflow/modules/ROOT/pages/getting-started/modules/proc-creating-workflow.adoc @@ -0,0 +1,78 @@ +:_content-type: PROCEDURE +:description: Creating a workflow +:keywords: create, serverless, workflow +:navtitle: Creating a workflow +// :page-aliases: + +[id="proc-creating-workflow_{context}"] += Creating a workflow + +After bootstrapping a project, you need to create a workflow. In the following procedure, a workflow named *Hello World Workflow* is created. + +.Procedure +. Create a file named `hello.sw.json` in the `src/main/resources` directory with the following content: ++ +-- +.Example content for `hello.sw.json` file +[source,json] +---- +{ + "id": "hello_world", <1> + "version": "1.0", + "specVersion": "0.8", + "name": "Hello World Workflow", + "description": "JSON based hello world workflow", + "start": "Inject Hello World", <3> + "states": [ <2> + { + "name": "Inject Hello World", + "type": "inject", <4> + "data": { <5> + "greeting": "Hello World" + }, + "transition": "Inject Mantra" <6> + }, + { + "name": "Inject Mantra", + "type": "inject", + "data": { + "mantra": "Serverless Workflow is awesome!" <7> + }, + "end": true <8> + } + ] +} +---- +In the previous example: + +<1> `id` field is the unique identifier of the workflow. {product_name} generates the REST endpoints based on this unique identifier. + +<2> `states` defines the states of the workflow. In the Hello World example, the workflow contains two states, such as `Inject Hello World` and `Inject Mantra`. + +<3> `start` field defines the state in which the workflow starts. + +<4> `type` defines the type of the state. In the previous example, the state is `inject`. The `inject` state can be used to inject static data into state data input. + +<5> `data` defines the data that is injected into the state. In the previous example, `greeting` is injected with the `Hello World` value. + +<6> `transition` field defines the next state that is reached after the current state is completed. + +<7> Injects a `mantra` with the value `Serverless Workflow is awesome!` into the workflow data. + +<8> `end` field defines that the current state is the end of the workflow. When the workflow reaches the end state, the workflow stops and the REST endpoint returns the workflow data, such as: + +.Example workflow data +[source,json] +---- +{ + "greeting": "Hello World", + "mantra": "Serverless Workflow is awesome!" +} +---- + +[NOTE] +==== +The workflow definition follows the CNCF Serverless Workflow specification. For more information, see +xref:getting-started/cncf-serverless-workflow-specification-support.adoc[CNCF Serverless Workflow specification]. +==== +-- diff --git a/serverlessworkflow/modules/ROOT/pages/getting-started/modules/proc-running-application.adoc b/serverlessworkflow/modules/ROOT/pages/getting-started/modules/proc-running-application.adoc new file mode 100644 index 000000000..1f99685b8 --- /dev/null +++ b/serverlessworkflow/modules/ROOT/pages/getting-started/modules/proc-running-application.adoc @@ -0,0 +1,145 @@ +:_content-type: PROCEDURE +:description: Running your workflow application +:keywords: run, serverless, workflow, application +:navtitle: Running your workflow application +// :page-aliases: + +[id="proc-running-application_{context}"] += Running your workflow application + +After creating a workflow, you can run your workflow application. + +.Procedure +. Enter the following command to run your workflow application: ++ + +[tabs] +==== +Quarkus CLI:: ++ +-- +.Run your workflow application using Quarkus CLI +[source,shell] +---- +quarkus dev +---- +-- +Apache Maven:: ++ +-- +.Run your workflow application using Apache Maven +[source,shell] +---- +mvn clean quarkus:dev +---- +-- +Knative workflow CLI: ++ +-- +Currently, Knative workflow CLI doesn't support yet running workflows locally. You can either: +.Run your workflow application using Apache Maven +[source,shell] +---- +mvn clean quarkus:dev +---- +.Run your workflow application using Quarkus CLI +[source,shell] +---- +quarkus dev +---- +For more information about Knative workflow CLI, see xref:tooling/kn-plugin-workflow-overview.adoc[{context} plug-in for Knative CLI]. +Also, to deploy and run your workflow application, see xref:cloud/deploying-on-minikube.adoc[Deploying workflow application on Minikube] +-- +==== ++ +.Example response +[source,shell,subs="attributes"] +---- +[INFO] ------< org.kie.kogito.examples:serverless-workflow-hello-world >------- +[INFO] Building serverless-workflow-hello-world 1.0 +[INFO] --------------------------------[ jar ]--------------------------------- +[INFO] +[INFO] --- quarkus-maven-plugin:{quarkus_version}:dev (default-cli) @ serverless-workflow-hello-world --- +[INFO] Invoking org.apache.maven.plugins:maven-resources-plugin:2.6:resources) @ serverless-workflow-hello-world +[INFO] Using 'UTF-8' encoding to copy filtered resources. +[INFO] Copying 3 resources +...more output... +__ ____ __ _____ ___ __ ____ ______ + --/ __ \/ / / / _ | / _ \/ //_/ / / / __/ + -/ /_/ / /_/ / __ |/ , _/ ,< / /_/ /\ \ +--\___\_\____/_/ |_/_/|_/_/|_|\____/___/ +2022-05-25 14:38:09,741 INFO [org.kie.kog.add.qua.mes.com.QuarkusKogitoExtensionInitializer] (Quarkus Main Thread) Registered Kogito CloudEvent extension +2022-05-25 14:38:09,840 INFO [io.quarkus] (Quarkus Main Thread) serverless-workflow-hello-world 1.0 on JVM (powered by Quarkus {quarkus_version}) started in 6.470s. Listening on: http://localhost:8080 +2022-05-25 14:38:09,843 INFO [io.quarkus] (Quarkus Main Thread) Profile dev activated. Live Coding activated. +2022-05-25 14:38:09,843 INFO [io.quarkus] (Quarkus Main Thread) Installed features: [cache, cdi, jackson-jq, kogito-addon-messaging-extension, kogito-processes, kogito-serverless-workflow, reactive-routes, rest-client, rest-client-jackson, resteasy, resteasy-jackson, smallrye-context-propagation, smallrye-openapi, smallrye-reactive-messaging, smallrye-reactive-messaging-http, swagger-ui, vertx] +2022-05-25 14:38:12,877 INFO [org.kie.kog.qua.pro.dev.DataIndexInMemoryContainer] (docker-java-stream--938264210) STDOUT: __ ____ __ _____ ___ __ ____ ______ +2022-05-25 14:38:12,878 INFO [org.kie.kog.qua.pro.dev.DataIndexInMemoryContainer] (docker-java-stream--938264210) STDOUT: --/ __ \/ / / / _ | / _ \/ //_/ / / / __/ +2022-05-25 14:38:12,879 INFO [org.kie.kog.qua.pro.dev.DataIndexInMemoryContainer] (docker-java-stream--938264210) STDOUT: -/ /_/ / /_/ / __ |/ , _/ ,< / /_/ /\ \ +2022-05-25 14:38:12,879 INFO [org.kie.kog.qua.pro.dev.DataIndexInMemoryContainer] (docker-java-stream--938264210) STDOUT: --\___\_\____/_/ |_/_/|_/_/|_|\____/___/ +2022-05-25 14:38:12,879 INFO [org.kie.kog.qua.pro.dev.DataIndexInMemoryContainer] (docker-java-stream--938264210) STDOUT: 2022-05-25 17:38:09,692 INFO [io.zon.tes.db.pos.emb.EmbeddedPostgres] (main) Detected a Linux x86_64 system +2022-05-25 14:38:12,880 INFO [org.kie.kog.qua.pro.dev.DataIndexInMemoryContainer] (docker-java-stream--938264210) STDOUT: 2022-05-25 17:38:09,705 INFO [io.zon.tes.db.pos.emb.DefaultPostgresBinaryResolver] (main) Detected distribution: 'Red Hat Enterprise Linux' +...more output... +2022-05-25 14:38:12,889 INFO [org.kie.kog.qua.pro.dev.DataIndexInMemoryContainer] (docker-java-stream--938264210) STDOUT: 2022-05-25 17:38:12,332 INFO [io.zon.tes.db.pos.emb.EmbeddedPostgres] (postgres:pid(90)) 2022-05-25 17:38:12.332 UTC [99] LOG: incomplete startup packet +2022-05-25 14:38:12,890 INFO [org.kie.kog.qua.pro.dev.DataIndexInMemoryContainer] (docker-java-stream--938264210) STDOUT: 2022-05-25 17:38:12,405 INFO [io.zon.tes.db.pos.emb.EmbeddedPostgres] (main) 5df1ed6e-7a15-4091-bcfb-e293aa293bfe postmaster startup finished in 00:00:00.180 +2022-05-25 14:38:12,890 INFO [org.kie.kog.qua.pro.dev.DataIndexInMemoryContainer] (docker-java-stream--938264210) STDOUT: 2022-05-25 17:38:12,405 INFO [org.kie.kog.per.inm.pos.run.InmemoryPostgreSQLRecorder] (main) Embedded Postgres started at port "44729" with database "postgres", user "postgres" and password "postgres" +2022-05-25 14:38:12,890 INFO [org.kie.kog.qua.pro.dev.DataIndexInMemoryContainer] (docker-java-stream--938264210) STDOUT: 2022-05-25 17:38:12,636 WARN [io.qua.run.con.ConfigRecorder] (main) Build time property cannot be changed at runtime: +2022-05-25 14:38:12,891 INFO [org.kie.kog.qua.pro.dev.DataIndexInMemoryContainer] (docker-java-stream--938264210) STDOUT: - quarkus.jib.base-jvm-image is set to 'ba-docker-registry.usersys.redhat.com:5000/fabric8/java-alpine-openjdk11-jre' but it is build time fixed to 'fabric8/java-alpine-openjdk11-jre'. Did you change the property quarkus.jib.base-jvm-image after building the application? +2022-05-25 14:38:13,375 INFO [org.kie.kog.qua.pro.dev.DataIndexInMemoryContainer] (docker-java-stream--938264210) STDOUT: 2022-05-25 17:38:13,105 INFO [org.kie.kog.per.pro.ProtobufService] (main) Registering Kogito ProtoBuffer file: kogito-index.proto +2022-05-25 14:38:13,377 INFO [org.kie.kog.qua.pro.dev.DataIndexInMemoryContainer] (docker-java-stream--938264210) STDOUT: 2022-05-25 17:38:13,132 INFO [org.kie.kog.per.pro.ProtobufService] (main) Registering Kogito ProtoBuffer file: kogito-types.proto +2022-05-25 14:38:13,378 INFO [org.kie.kog.qua.pro.dev.DataIndexInMemoryContainer] (docker-java-stream--938264210) STDOUT: 2022-05-25 17:38:13,181 INFO [io.quarkus] (main) data-index-service-inmemory 1.22.0.Final on JVM (powered by Quarkus 2.9.0.Final) started in 4.691s. Listening on: http://0.0.0.0:8080 +2022-05-25 14:38:13,379 INFO [org.kie.kog.qua.pro.dev.DataIndexInMemoryContainer] (docker-java-stream--938264210) STDOUT: 2022-05-25 17:38:13,182 INFO [io.quarkus] (main) Profile prod activated. +2022-05-25 14:38:13,380 INFO [org.kie.kog.qua.pro.dev.DataIndexInMemoryContainer] (docker-java-stream--938264210) STDOUT: 2022-05-25 17:38:13,182 INFO [io.quarkus] (main) Installed features: [agroal, cdi, hibernate-orm, hibernate-orm-panache, inmemory-postgres, jdbc-postgresql, narayana-jta, oidc, reactive-routes, rest-client-reactive, rest-client-reactive-jackson, security, smallrye-context-propagation, smallrye-graphql-client, smallrye-health, smallrye-metrics, smallrye-reactive-messaging, smallrye-reactive-messaging-http, vertx, vertx-graphql] +---- + +. Once your workflow application is started, you can send a request for the provided endpoint: ++ + ++ +.Example request +[source,shell] +---- +curl -X POST -H 'Content-Type:application/json' http://localhost:8080/hello_world +---- + ++ +-- +.Example response +[source,shell] +---- +{"id":"efb59bfa-ad9c-4062-a6d2-2d9184dd4b3d","workflowdata":{"greeting":"Hello World","mantra":"Serverless Workflow is awesome!"}} +---- +-- + +. When running in development mode (using Quarkus CLI or Apache Maven), you can update your workflow with a new `mantra` value without restarting the application. ++ +-- +.Update your workflow +[source,json] +---- +{ + "name": "Inject Mantra", + "type": "inject", + "data": { + "mantra": "Serverless Workflow is amazing!" <1> + }, + "end": true +} +---- +<1> New `mantra` value + +.Example request +[source,shell] +---- +curl -X POST -H 'Content-Type:application/json' http://localhost:8080/hello_world +---- + +.Example response +[source,shell] +---- +{"id":"efb59bfa-ad9c-4062-a6d2-2d9184dd4b3d","workflowdata":{"greeting":"Hello World","mantra":"Serverless Workflow is amazing!"}} +---- + +Note that the `mantra` value is updated without restarting the application, because {product_name} leverages the Quarkus live coding feature. +-- + +. To stop the application, press `CTRL+C`. diff --git a/serverlessworkflow/modules/ROOT/pages/getting-started/modules/proc-testing-application.adoc b/serverlessworkflow/modules/ROOT/pages/getting-started/modules/proc-testing-application.adoc new file mode 100644 index 000000000..9538279e0 --- /dev/null +++ b/serverlessworkflow/modules/ROOT/pages/getting-started/modules/proc-testing-application.adoc @@ -0,0 +1,11 @@ +:_content-type: PROCEDURE +:description: Testing your workflow application +:keywords: test, serverless, workflow, application +:navtitle: Testing your workflow application +// :page-aliases: + +[id="proc-testing-application_{context}"] += Testing your workflow application + +To test your workflow application, you can follow the instructions in the +xref:testing-and-troubleshooting/basic-integration-tests-with-restassured.adoc[Testing your workflow application using REST Assured]. diff --git a/serverlessworkflow/modules/ROOT/pages/getting-started/nav.adoc b/serverlessworkflow/modules/ROOT/pages/getting-started/nav.adoc new file mode 100644 index 000000000..f2631f6a7 --- /dev/null +++ b/serverlessworkflow/modules/ROOT/pages/getting-started/nav.adoc @@ -0,0 +1,4 @@ +.Getting Started +** xref:getting-started/modules/create-your-first-workflow-service.adoc[Creating your first workflow service] +** xref:getting-started/cncf-serverless-workflow-specification-support.adoc[CNCF Serverless Workflow specification] +** xref:getting-started/getting-familiar-with-our-tooling.adoc[Getting familiar with {context} tooling]