Introduction to SonataFlow development

This guide showcases the SonataFlow Workflow CLI plugin and Apache KIE Serverless Workflow Visual Studio code extension to create, run & deploy SonataFlow projects on your local environment and walks you trhought the recommended development loop of workflow applications.

Prerequisites

Creating a workflow project with KN CLI

Use the create command with kn workflow to scaffold a new SonataFlow project.

Procedure

  1. Navigate to your development directory and create your project.

    kn workflow create -n my-sonataflow-project
    bash

  2. This will create a folder with name my-sonataflow-project and a sample workflow workflow.sw.json

    cd ./my-sonataflow-project
    bash

  3. Open the folder in Visual Studio Code and examine or the created workflow.sw.json using the editor provided by the extension.

    code workflow.sw.json
    bash

Now you can run the project and execute the workflow.

Running a workflow project with KN CLI

Use the run command with kn workflow to build and run the SonataFlow project locally in development mode.

Procedure

  1. Run the project.

    kn workflow run
    bash

    • 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 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 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 Serverless Workflow Specification and guides in Core chapter first.

Executing a workflow

  1. To test your running workflow project, access the Swagger UI on localhost:8080/q/swagger-ui to examine available endpoints.

  2. In order to execute the workflow once, run:

curl -X 'POST' \
  'localhost:8080/hello' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -d '{
  "workflowdata": {}
}'

  1. You should see a similar response:

    {"id": "<UUID>", "workflowdata" : {"message":"Hello World"}}
    bash

To deploy the finished project to kubernetes cluster, proceed to the next section.

Deploying a workflow project with KN CLI

Prerequisites

Use the deploy command with kn workflow to deploy the SonataFlow project into your local cluster.

Procedure

  1. Create a namespace for your application

    kubectl create namespace my-sf-application
    bash

  2. Deploy the workflow to the cluster in the default dev mode. The plugin uses settings located in ./<home>/.kube/config to access the cluster.

    kn workflow deploy --namespace my-sf-application
    bash

    • In a separate bash instance create a port mapping:

      • Openshift

      • Minikube

      • Kind

      oc get route svc/hello --namespace my-sf-application
      shell

      • 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>/q/dev-ui/org.apache.kie.sonataflow.sonataflow-quarkus-devui/workflows

      minikube service hello --namespace my-sf-application --url
      shell

      • Use this URL to access your workflow instances using the Developer UI

        • <RETURNED_URL>/q/dev-ui/org.apache.kie.sonataflow.sonataflow-quarkus-devui/workflows

      # Execute
kubectl get services -n my-sf-application

# You should see output like this, note the ports
NAME         TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)            AGE
hello        ClusterIP   10.96.0.1    <none>        <RANDOM_PORT>/80   39s

# Execute
kubectl port-forward service/hello <RANDOM_PORT>:80 -n my-sf-application
      shell

    • 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.

  3. To stop the deployment, use the undeploy command:

    kn workflow undeploy --namespace my-sf-application
    bash

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, 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

Found an issue?

If you find an issue or any misleading information, please feel free to report it here. We really appreciate it!