Chapter 6. Workflow eventing system You can set up the eventing system for a SonataFlow workflow. In a OpenShift Serverless Logic installation, the following types of events are generated: Outgoing and incoming events related to workflow business logic. Events sent from workflows to the Data Index and Job Service. Events sent from the Job Service to the Data Index Service. The OpenShift Serverless Logic Operator leverages the Knative Eventing system to manage all event communication between these services, ensuring efficient and reliable event handling. 6.1. Platform-scoped eventing system configuration To configure a platform-scoped eventing system, you can use the spec.eventing.broker.ref field in the SonataFlowPlatform custom resource (CR) to reference a Knative Eventing broker. This configuration instructs the OpenShift Serverless Logic Operator to automatically link every workflow deployed in the specified namespace, using the preview or gitops profile, to produce and consume events through the defined broker. The supporting services deployed in the namespace without a custom eventing configuration are also linked to this broker. Note In production environments, use a production-ready broker, such as the Knative Kafka Broker, for enhanced scalability and reliability. The following example displays how to configure the SonataFlowPlatform CR for a platform-scoped eventing system: apiVersion: sonataflow.org/v1alpha08 kind: SonataFlowPlatform metadata: name: sonataflow-platform-example namespace: <example-namespace> spec: eventing: broker: ref: name: example-broker 1 namespace: <example-broker-namespace> 2 apiVersion: eventing.knative.dev/v1 kind: Broker 1 Specifies the Knative Eventing Broker name. 2 Optional: Specifies the namespace of the Knative Eventing Broker. If you do not sepcify the value, then the parameter defaults to the namespace of the SonataFlowPlatform CR. Consider creating the broker in the same namespace as SonataFlowPlatform . 6.2. Workflow-scoped eventing system configuration A workflow-scoped eventing system configuration allows for detailed customization of the events produced and consumed by a specific workflow. You can use the spec.sink.ref and spec.sources[] fields in the SonataFlow CR to configure outgoing and incoming events. 6.2.1. Outgoing eventing system configuration To configure outgoing events, you can use the spec.sink.ref field in the SonataFlow CR. This configuration ensures the workflow produces events using the specified Knative Eventing Broker, including both system events and workflow business events. The following example displays how to configure the SonataFlow CR for a workflow-scoped outgoing eventing system: apiVersion: sonataflow.org/v1alpha08 kind: SonataFlow metadata: name: example-workflow namespace: example-workflow-namespace annotations: sonataflow.org/description: Example Workflow sonataflow.org/version: 0.0.1 sonataflow.org/profile: preview spec: sink: ref: name: outgoing-example-broker 1 namespace: outgoing-example-broker-namespace 2 apiVersion: eventing.knative.dev/v1 kind: Broker flow: 3 start: ExampleStartState events: 4 - name: outEvent1 5 source: '' kind: produced type: out-event-type1 6 ... 1 Name of the Knative Eventing Broker to use for all the events produced by the workflow, including the SonataFlow system events. 2 Defines the namespace of the Knative Eventing Broker. If you do not specify a value, the parameter defaults to the SonataFlow namespace. Consider creating the broker in the same namespace as SonataFlow . 3 Flow definition field in the SonataFlow CR. 4 Events definition field in the SonataFlow CR. 5 Example of an outgoing event outEvent1 definition. 6 Event type for the outEvent1 outgoing event. 6.2.2. Incoming eventing system configuration To configure incoming events, you can use the spec.sources[] field in the SonataFlow CR. You can add an entry for each event type requiring specific configuration. This setup allows workflows to consume events from different brokers based on event type. If an incoming event type lacks a specific Broker configuration, the system applies eventing system configuration precedence rules. The following example displays how to configure the SonataFlow CR for a workflow-scoped incoming eventing system: Note The link between a spec.sources[] entry and the workflow event, is by using the event type. apiVersion: sonataflow.org/v1alpha08 kind: SonataFlow metadata: name: example-workflow namespace: example-workflow-namespace annotations: sonataflow.org/description: Example Workflow sonataflow.org/version: 0.0.1 sonataflow.org/profile: preview spec: sources: - eventType: in-event-type1 1 ref: name: incoming-example-broker1 2 namespace: incoming-example-broker1-namespace 3 apiVersion: eventing.knative.dev/v1 kind: Broker - eventType: in-event-type2 4 ref: name: incoming-example-broker2 5 namespace: incoming-example-broker2-namespace 6 apiVersion: eventing.knative.dev/v1 kind: Broker flow: 7 start: ExampleStartState events: 8 - name: inEvent1 9 source: '' kind: consumed type: in-event-type1 10 - name: inEvent2 11 source: '' kind: consumed type: in-event-type2 12 ... 1 Configure the workflow to consume events of type in-event-type1 using the specified Knative Eventing Broker. 2 Name of the Knative Eventing Broker to use for the consumption of the events of type in-event-type1 sent to this workflow. 3 Optional: If you do not specify the value, the parameter defaults to the SonataFlow namespace. Consider creating the broker in the same namespace as the SonataFlow workflow. 4 Configure the workflow to consume events of type in-event-type2 using the specified Knative Eventing Broker. 5 Name of the Knative Eventing Broker to use for the consumption of the events of type in-event-type2 sent to this workflow. 6 Optional: If you do not specify the value, the parameter defaults to the SonataFlow namespace. Consider creating the broker in the same namespace as the SonataFlow workflow. 7 Flow definition field in the SonataFlow CR. 8 Events definition field in the SonataFlow CR. 9 Example of an incoming event inEvent1 definition. 10 Event type for the incoming event inEvent1 . The link of the workflow event, with the corresponding spec.sources[] entry, is by using the event type name in-event-type1 . 11 Example of an incoming event inEvent2 definition. 12 Event type for the incoming event inEvent2 . The link of the workflow event, with the corresponding spec.sources[] entry, is created by using the event type name in-event-type2. 6.3. Cluster-scoped eventing system configuration In a SonataFlowClusterPlatform setup, workflows are automatically linked to the Broker specified in the associated SonataFlowPlatform CR. This linkage follows the Eventing System configuration precedence rules. To ensure proper integration, you can configure Broker in the SonataFlowPlatform CR referenced by the SonataFlowClusterPlatform CR. The following example displays how to configure the SonataFlowClusterPlatform CR and its reference to the SonataFlowPlatform CR: apiVersion: sonataflow.org/v1alpha08 kind: SonataFlowPlatform metadata: name: global-platform namespace: global-namespace spec: eventing: broker: ref: name: global-broker namespace: global-namespace apiVersion: eventing.knative.dev/v1 kind: Broker --- apiVersion: sonataflow.org/v1alpha08 kind: SonataFlowClusterPlatform metadata: name: cluster-platform-example spec: platformRef: name: global-platform namespace: global-namespace ... Note The SonataFlowClusterPlatform CR can refer to any SonataFlowPlatform CR that has already been deployed. 6.4. Eventing system configuration precedence rules The OpenShift Serverless Logic Operator follows a defined order of precedence to determine the eventing system configuration for a workflow. Eventing system configuration precedence rules are as follows: If the workflow has a defined eventing system by using either workflow-scoped outgoing or incoming eventing system configurations, the choice of configuration takes priority over the other configuration and applies to the workflow. If the SonataFlowPlatform CR enclosing the workflow has a platform-scoped eventing system configured, this configuration is then applied to the step. If the current cluster is configured with a cluster-scoped eventing system, it is applied if no workflow-scoped or platform-scoped configuration exists. Review the following information, if none of the above configurations are defined: The workflow uses direct HTTP calls to deliver SonataFlow system events to supporting services. The workflow consumes incoming events by HTTP POST calls at the workflow service root path / . No eventing system is configured to produce workflow business events. Any attempt to produce such events might result in a failure. 6.5. Linking workflows to the eventing system The OpenShift Serverless Logic Operator links workflows with the eventing system using Knative Eventing, SinkBindings, and triggers. These objects are created automatically by the OpenShift Serverless Logic Operator and simplify the production and consumption of workflow events. The following example shows the Knative Eventing objects created for an example-workflow workflow configured with a platform-scoped eventing system: apiVersion: sonataflow.org/v1alpha08 kind: SonataFlowPlatform metadata: name: sonataflow-platform-example namespace: example-namespace spec: eventing: broker: ref: name: example-broker 1 apiVersion: eventing.knative.dev/v1 kind: Broker services: dataIndex: 2 enabled: true jobService: 3 enabled: true ... 1 The example-broker object is used by the Data Index, Jobs Service, and the example-workflow workflow. 2 The Data Index is deployed with ephemeral configurations. 3 The Jobs Service is deployed with ephemeral configurations. The example-broker object is a Kafka class Broker, and its configuration is defined in the kafka-broker-config config map. The following example displays how to configure a Kafka Knative Broker for use with the SonataFlowPlatform: apiVersion: eventing.knative.dev/v1 kind: Broker metadata: annotations: eventing.knative.dev/broker.class: Kafka 1 name: example-broker namespace: example-namespace spec: config: apiVersion: v1 kind: ConfigMap name: kafka-broker-config namespace: knative-eventing 1 The Kafka class is used to create the example-broker object. The following example displays how the example-workflow is automatically linked to the example-broker in the example-namespace for event production and consumption: apiVersion: sonataflow.org/v1alpha08 kind: SonataFlow metadata: name: example-workflow namespace: example-namespace annotations: sonataflow.org/description: Example Workflow sonataflow.org/version: 0.0.1 sonataflow.org/profile: preview spec: flow: start: ExampleStartState events: - name: outEvent1 source: '' kind: produced type: out-event-type1 1 - name: inEvent1 source: '' kind: consumed type: in-event-type1 2 - name: inEvent2 source: '' kind: consumed type: in-event-type2 3 states: - name: ExampleStartState ... 1 The example-workflow outgoing events are produced by using the SinkBinding named example-workflow-sb . 2 Events of type in-event-type1 are consumed by using the example-workflow-inevent1-b40c067c-595b-4913-81a4-c8efa980bc11 trigger. 3 Events of type in-event-type2 are consumed by using the example-workflow-inevent2-b40c067c-595b-4913-81a4-c8efa980bc11 trigger. You can list the automatically created SinkBinding named example-workflow-sb by using the following command: USD oc get sinkbindings -n example-namespace Example output NAME TYPE RESOURCE SINK READY example-workflow-sb SinkBinding sinkbindings.sources.knative.dev broker:example-broker True You can use the following command to list the automatically created triggers for event consumption: USD oc get triggers -n <example-namespace> Example output NAME BROKER SINK AGE CONDITIONS READY REASON example-workflow-inevent1-b40c067c-595b-4913-81a4-c8efa980bc11 example-broker service:example-workflow 16m 7 OK / 7 True example-workflow-inevent2-b40c067c-595b-4913-81a4-c8efa980bc11 example-broker service:example-workflow 16m 7 OK / 7 True

Commands:
apiVersion: sonataflow.org/v1alpha08 kind: SonataFlowPlatform metadata: name: sonataflow-platform-example namespace: <example-namespace> spec: eventing: broker: ref: name: example-broker 1 namespace: <example-broker-namespace> 2 apiVersion: eventing.knative.dev/v1 kind: Broker
apiVersion: sonataflow.org/v1alpha08 kind: SonataFlow metadata: name: example-workflow namespace: example-workflow-namespace annotations: sonataflow.org/description: Example Workflow sonataflow.org/version: 0.0.1 sonataflow.org/profile: preview spec: sink: ref: name: outgoing-example-broker 1 namespace: outgoing-example-broker-namespace 2 apiVersion: eventing.knative.dev/v1 kind: Broker flow: 3 start: ExampleStartState events: 4 - name: outEvent1 5 source: '' kind: produced type: out-event-type1 6
apiVersion: sonataflow.org/v1alpha08 kind: SonataFlow metadata: name: example-workflow namespace: example-workflow-namespace annotations: sonataflow.org/description: Example Workflow sonataflow.org/version: 0.0.1 sonataflow.org/profile: preview spec: sources: - eventType: in-event-type1 1 ref: name: incoming-example-broker1 2 namespace: incoming-example-broker1-namespace 3 apiVersion: eventing.knative.dev/v1 kind: Broker - eventType: in-event-type2 4 ref: name: incoming-example-broker2 5 namespace: incoming-example-broker2-namespace 6 apiVersion: eventing.knative.dev/v1 kind: Broker flow: 7 start: ExampleStartState events: 8 - name: inEvent1 9 source: '' kind: consumed type: in-event-type1 10 - name: inEvent2 11 source: '' kind: consumed type: in-event-type2 12
apiVersion: sonataflow.org/v1alpha08 kind: SonataFlowPlatform metadata: name: global-platform namespace: global-namespace spec: eventing: broker: ref: name: global-broker namespace: global-namespace apiVersion: eventing.knative.dev/v1 kind: Broker --- apiVersion: sonataflow.org/v1alpha08 kind: SonataFlowClusterPlatform metadata: name: cluster-platform-example spec: platformRef: name: global-platform namespace: global-namespace
apiVersion: sonataflow.org/v1alpha08 kind: SonataFlowPlatform metadata: name: sonataflow-platform-example namespace: example-namespace spec: eventing: broker: ref: name: example-broker 1 apiVersion: eventing.knative.dev/v1 kind: Broker services: dataIndex: 2 enabled: true jobService: 3 enabled: true
apiVersion: eventing.knative.dev/v1 kind: Broker metadata: annotations: eventing.knative.dev/broker.class: Kafka 1 name: example-broker namespace: example-namespace spec: config: apiVersion: v1 kind: ConfigMap name: kafka-broker-config namespace: knative-eventing
apiVersion: sonataflow.org/v1alpha08 kind: SonataFlow metadata: name: example-workflow namespace: example-namespace annotations: sonataflow.org/description: Example Workflow sonataflow.org/version: 0.0.1 sonataflow.org/profile: preview spec: flow: start: ExampleStartState events: - name: outEvent1 source: '' kind: produced type: out-event-type1 1 - name: inEvent1 source: '' kind: consumed type: in-event-type1 2 - name: inEvent2 source: '' kind: consumed type: in-event-type2 3 states: - name: ExampleStartState
oc get sinkbindings -n example-namespace
NAME TYPE RESOURCE SINK READY example-workflow-sb SinkBinding sinkbindings.sources.knative.dev broker:example-broker True
oc get triggers -n <example-namespace>
NAME BROKER SINK AGE CONDITIONS READY REASON example-workflow-inevent1-b40c067c-595b-4913-81a4-c8efa980bc11 example-broker service:example-workflow 16m 7 OK / 7 True example-workflow-inevent2-b40c067c-595b-4913-81a4-c8efa980bc11 example-broker service:example-workflow 16m 7 OK / 7 True