[kie-kogito-examples-2041] [sonataflow] Implement a getting started example for operator use case

serverless-operator-examples/README.md

@@ -0,0 +1,13 @@
+ Serverless Operator Examples
+
+## Description
+
+In this folder, you can find examples showcasing SonataFlow applications and their development on Cloud environment. These examples are suitable if you would like to work with SonataFlow without the need to work with Java and Quarkus.
+
+
+## Requirements
+
+* Docker or Podman, required for local development scenarios.
+* Access to a Kubernetes cluster.
+* Worklow plugin for KN CLI installed.
+* Visual Studio Code with serverless workflow editor extension installed.

serverless-operator-examples/serverless-workflow-get-random-catfact/README.md

@@ -0,0 +1,64 @@
+# {product_name} Operator - Get Random Cat Fact Example
+
+## Description
+
+The goal of this example is to showcase use of [{product_name} plugin for Knative CLI](https://sonataflow.org/serverlessworkflow/main/testing-and-troubleshooting/kn-plugin-workflow-overview.html) for local development and subsequent deployment of finished {product_name} application.
+
+### Use Case
+
+This example is doing basic decision based on input provided to the workflow. If the input matches a string, workflow will query a specific endpoint and store the result, otherwise it uses a static string.
+The example contains workflow definition, necessary application.properties and an openAPI spec file to be able to query external service.
+
+### Prerequisites
+
+1. Install [{product_name} plugin for Knative CLI](https://sonataflow.org/serverlessworkflow/main/testing-and-troubleshooting/kn-plugin-workflow-overview.html)
+2. Install the [Operator](https://kiegroup.github.io/kogito-docs/serverlessworkflow/latest/cloud/operator/install-serverless-operator.html)
+3. Checkout this example locally
+
+### Run the example in local environment
+
+In order to ensure the developed workflows does what it is meant to do, `run` command allows users to spin up a container in development mode on localhost. A [management console](https://sonataflow.org/serverlessworkflow/main/testing-and-troubleshooting/quarkus-dev-ui-extension/quarkus-dev-ui-overview.html) is available for users to play with the workflows.
+
+1. Navigate to the root directory of the example
+2. Execute `kn workflow run`
+3. Navigate to `http://localhost:8080/q/dev-ui/org.apache.kie.sonataflow.sonataflow-quarkus-devui/workflows` to access the management console
+4. You can modify the project, any changes will be detected and the container will update
+
+### Deploy the example to cluster
+
+Once the workflow is stable and working, `deploy` command allows users to create deployments of the workflow on the targetted cluster. To deploy a workflow application, [{product_name} plugin for Knative CLI](https://sonataflow.org/serverlessworkflow/main/testing-and-troubleshooting/kn-plugin-workflow-overview.html) relies on configuration in `<home_directory>/.kube/config`. If you cluster has managed access, users need to login prior to the use of CLI.
+
+1. Create a namespace for your deployment `oc create namespace catfactexample`
+2. Navigate to the root directory of the example
+3. Execute `kn workflow deploy -n catfactexample`
+4. Access your cluster, you should see new deployment in `catfactexample` namespace
+5. Management console can be accessed on the `<WORKFLOW_GENERATED_ROUTE_URL>/q/dev-ui/org.apache.kie.sonataflow.sonataflow-quarkus-devui/workflows`
+
+### Undeploy the example from cluster
+
+In order to get rid of the deployment, `undeploy` command allows user to cleanup the deployed resources.
+
+1. Navigate to the root directory of the example.
+2. Execute `kn workflow undeploy -n catfactexample`
+3. The namespace is now clean and without any resources.
+
+### Deploy the example to cluster with different configuration
+
+By default, `deploy` command generates the Kubernetes definitions during the deployment. In order to customize these files, use `--custom-generated-manifests-dir=./manifests` parameter to store the generated Kubernetes manifests. Once modified, use `--custom-manifests-dir=./manifests` to use the already generated manifests.
+
+1. Navigate to the root directory of the example.
+2. Execute `kn workflow deploy -n catfactexample --custom-generated-manifests-dir=./manifests`
+3. Navigate to the `/.manifests` folder and modify the files.
+4. Navigate to root directory of the example.
+5. Execute `kn workflow deploy -n catfactexample --custom-manifests-dir=./manifests`
+
+Another option is to use `gen-manifest` to create the Kubernetes manifests, run `kn workflow gen-manifest --help` to see the documentation for this command. The procedure to deploy is as follows:
+
+1. Navigate to the root directory of the example.
+2. Execute `kn workflow gen-manifest -n catfactexample --profile=preview --custom-generated-manifests-dir=./manifests`
+3. Execute `kn workflow deploy -n catfactexample --custom-manifests-dir=./manifests`
+4. The workflow is now deployed with `sonataflow.org/profile: preview` annotation.
+
+
+Once the application is deployed, you can trigger the workflows. This is as simple as sending a
+HTTP POST request to the endpoint of your workflow application. For example `curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{"fact":"random"}' http://<URL_TO_HOST>/getcatfactinformation` where `URL_TO_HOST` depends on the environment you are in.

serverless-operator-examples/serverless-workflow-get-random-catfact/application.properties

@@ -0,0 +1 @@
+quarkus.rest-client.catfacts_json.url=https://catfact.ninja

serverless-operator-examples/serverless-workflow-get-random-catfact/specs/catfacts.json

@@ -0,0 +1,204 @@
+{
+    "openapi": "3.0.0",
+    "info": {
+        "title": "Cat Fact API",
+        "description": "An API for facts about cats",
+        "contact": {
+            "email": "[email protected]"
+        },
+        "version": "1.0.0"
+    },
+    "paths": {
+        "/breeds": {
+            "get": {
+                "tags": [
+                    "Breeds"
+                ],
+                "summary": "Get a list of breeds",
+                "description": "Returns a a list of breeds",
+                "operationId": "getBreeds",
+                "parameters": [
+                    {
+                        "name": "limit",
+                        "in": "query",
+                        "description": "limit the amount of results returned",
+                        "required": false,
+                        "schema": {
+                            "type": "integer",
+                            "format": "int64"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "successful operation",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "array",
+                                    "items": {
+                                        "$ref": "#/components/schemas/Breed"
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "/fact": {
+            "get": {
+                "tags": [
+                    "Facts"
+                ],
+                "summary": "Get Random Fact",
+                "description": "Returns a random fact",
+                "operationId": "getRandomFact",
+                "parameters": [
+                    {
+                        "name": "max_length",
+                        "in": "query",
+                        "description": "maximum length of returned fact",
+                        "required": false,
+                        "schema": {
+                            "type": "integer",
+                            "format": "int64"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "successful operation",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/CatFact"
+                                }
+                            }
+                        }
+                    },
+                    "404": {
+                        "description": "Fact not found"
+                    }
+                }
+            }
+        },
+        "/facts": {
+            "get": {
+                "tags": [
+                    "Facts"
+                ],
+                "summary": "Get a list of facts",
+                "description": "Returns a a list of facts",
+                "operationId": "getFacts",
+                "parameters": [
+                    {
+                        "name": "max_length",
+                        "in": "query",
+                        "description": "maximum length of returned fact",
+                        "required": false,
+                        "schema": {
+                            "type": "integer",
+                            "format": "int64"
+                        }
+                    },
+                    {
+                        "name": "limit",
+                        "in": "query",
+                        "description": "limit the amount of results returned",
+                        "required": false,
+                        "schema": {
+                            "type": "integer",
+                            "format": "int64"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "successful operation",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "array",
+                                    "items": {
+                                        "$ref": "#/components/schemas/CatFact"
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    },
+    "components": {
+        "schemas": {
+            "Breed": {
+                "title": "Breed model",
+                "description": "Breed",
+                "properties": {
+                    "breed": {
+                        "title": "Breed",
+                        "description": "Breed",
+                        "type": "string",
+                        "format": "string"
+                    },
+                    "country": {
+                        "title": "Country",
+                        "description": "Country",
+                        "type": "string",
+                        "format": "string"
+                    },
+                    "origin": {
+                        "title": "Origin",
+                        "description": "Origin",
+                        "type": "string",
+                        "format": "string"
+                    },
+                    "coat": {
+                        "title": "Coat",
+                        "description": "Coat",
+                        "type": "string",
+                        "format": "string"
+                    },
+                    "pattern": {
+                        "title": "Pattern",
+                        "description": "Pattern",
+                        "type": "string",
+                        "format": "string"
+                    }
+                },
+                "type": "object"
+            },
+            "CatFact": {
+                "title": "CatFact model",
+                "description": "CatFact",
+                "properties": {
+                    "fact": {
+                        "title": "Fact",
+                        "description": "Fact",
+                        "type": "string",
+                        "format": "string"
+                    },
+                    "length": {
+                        "title": "Length",
+                        "description": "Length",
+                        "type": "integer",
+                        "format": "int32"
+                    }
+                },
+                "type": "object"
+            }
+        }
+    },
+    "tags": [
+        {
+            "name": "Facts",
+            "description": "Cat Facts"
+        },
+        {
+            "name": "Breeds",
+            "description": "Breeds"
+        }
+    ]
+}

serverless-operator-examples/serverless-workflow-get-random-catfact/workflow.sw.json

@@ -0,0 +1,79 @@
+{
+  "id": "getCatFactInformation",
+  "version": "1.0",
+  "specVersion": "0.8.0",
+  "name": "Get cat fact",
+  "description": "Description",
+  "start": "GreetOrCatFact",
+   "functions": [
+      {
+         "name": "getCatFact",
+         "operation": "specs/catfacts.json#getRandomFact"
+      },
+      {
+        "name": "sysOutFunction",
+        "type": "custom",
+        "operation": "sysout"
+      }
+   ],
+  "states": [
+    {
+      "name": "GreetOrCatFact",
+      "type": "switch",
+      "dataConditions": [
+        {
+          "condition": "${ .fact == \"random\"}",
+          "transition": "GetRandomFact"
+        }
+      ],
+      "timeouts": {
+        "stateExecTimeout": "P4D",
+        "eventTimeout" : "P4D"
+      },
+      "defaultCondition": {
+        "transition": "GetOneStaticFact"
+      }
+    },
+    {
+      "name": "GetOneStaticFact",
+      "type": "inject",
+      "data": {
+        "message": "Cats are very cute"
+      },
+      "transition": "PrintTheFact"
+    },
+    {
+      "name": "GetRandomFact",
+      "type": "operation",
+      "actions": [
+        {
+          "name": "getRandomFact",
+          "functionRef": {
+              "refName": "getCatFact"
+          }
+        }
+      ],
+      "transition": "PrintTheFact",
+      "timeouts": {
+        "stateExecTimeout": "P4D",
+        "eventTimeout" : "P4D"
+      }
+    },
+    {
+      "name": "PrintTheFact",
+      "type": "operation",
+      "actions": [
+        {
+          "name": "greetAction",
+          "functionRef": {
+            "refName": "sysOutFunction",
+            "arguments": {
+              "message": "${\"Fact is that: \" + .message + .fact }"
+            }
+          }
+        }
+      ],
+      "end": true
+    }
+  ]
+}