Referencing Additional Files in the Workflow

This document describes how to reference additional files in the SonataFlow Custom Resource (CR).

Most of the time, a workflow definition will require not only the flow definition, but also OpenAPI or AsyncAPI specification descriptors, schemas, subflows definitions, and etc. For example, when doing service orchestration using OpenAPI descriptors, you need to tell the workflow where to find these descriptors in your context.

If these files are not in a remote location that can be accessed via the HTTP protocol, you must describe in the SonataFlow CR where to find them within the cluster. This is done via ConfigMaps.

Creating ConfigMaps with Workflow Additional Files

Prerequisites

You have the files available in your file system
You have permissions to create ConfigMaps in the target namespace

Given that you already have the file you want to add to your workflow definition, you can create a ConfigMap as you normally would with the contents of the file.

For example, given the following workflow:

Example of a workflow referencing additional files

apiVersion: sonataflow.org/v1alpha08
kind: SonataFlow
metadata:
  name: service
  annotations:
    sonataflow.org/description: Hello Service!
    sonataflow.org/version: 0.0.1
    sonataflow.org/profile: dev
spec:
  flow:
    start: Service
    dataInputSchema: specs/workflow-service-schema.json (1)
    functions:
    - name: isWinner
      operation: specs/workflow-service-openapi.json#isWinner (2)
      type: rest
    states:
    - name: Service
      type: operation
      actions:
      - name: CallService
        functionRef:
          refName: isWinner
    end: true

1	The workflow defines an input schema
2	The workflow requires an OpenAPI specification file to make a REST invocation

For this example, you have two options. You can either create two ConfigMaps to have a clear separation of concerns or only one with both files.

From the operator perspective, it won’t make any difference since both files will be available for the workflow application at runtime.

To make it simple, you can create only one ConfigMap. Given that the files are available in the current directory:

Creating a ConfigMap from the current directory

kubectl create configmap service-files --from-file=$(pwd) -n <workflow-namespace>

Replace <workflow-namespace> with the namespace where you are going to deploy the workflow. The operator won’t access ConfigMaps in other namespaces.

You should have a ConfigMap with two data entries similar to this one:

Example of a ConfigMap containing the data for the worflow

kind: ConfigMap
apiVersion: v1
metadata:
  name: service-files
data:
  workflow-service-schema.json: # data was removed to save space
  workflow-service-openapi.json: # data was removed to save space

Now you can reference this ConfigMap to your SonataFlow CR:

SonataFlow CR referencing a ConfigMap resource

apiVersion: sonataflow.org/v1alpha08
kind: SonataFlow
metadata:
  name: service
  annotations:
    sonataflow.org/description: Hello Service!
    sonataflow.org/version: 0.0.1
    sonataflow.org/profile: dev
spec:
  resources: (1)
    configMaps:
      - configMap:
          name: service-files (2)
        workflowPath: specs (3)
  flow:
    start: Service
    dataInputSchema: specs/workflow-service-schema.json
    functions:
    - name: isWinner
      operation: specs/workflow-service-openapi.json#isWinner
      type: rest
    states:
    - name: Service
      type: operation
      actions:
      - name: CallService
        functionRef:
          refName: isWinner
    end: true

1	Introduced a new attribute `.spec.resources` where you can bind the `ConfigMap` to the `SonataFlow` CR
2	The name of the `ConfigMap` in the same namespace
3	The path where we want to reference these files

Note that the workflowPath is specs. This is the path where you want to reference the files within the ConfigMap in the workflow definition.

Always create your ConfigMaps before the SonataFlow since not having the files available during startup might break the deployment.

Any files you have to map to the flow definition can be added to the SonataFlow CR using this procedure.

Creating a Static Service Registry

The ConfigMap containing workflow files are not tied to a particular SonataFlow instance, just referenced by it. It means that the operator won’t edit or delete them if the SonataFlow CR is updated or deleted. You have total control of the ConfigMap instance.

You can organize your ConfigMaps in a way that other workflows could reuse them. In other words, one ConfigMap can be mapped to many SonataFlow Custom Resources.

For example, if you have many OpenAPI or AsyncAPI specification files that your workflows can access, you can group them by domain. This way you create a static Service Registry using ConfigMaps. Other developers within your company can reuse the same specification files when designing workflows.

The same applies for data input and output schemas, subflows definitions, and so on.

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!