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 referencing additional files

Prerequisites

  • You have set up your environment according to the minimal environment setup guide.

  • You have the cluster instance up and running. See starting the cluster for local development guide.

  • You have permissions to create ConfigMaps in the target namespace of your cluster.

  • (Optional) You have the files that you want to reference in your workflow definition ready.

If you already have the files referenced in your workflow definition, you can create a ConfigMap in your target namespace with the contents of the file.

In the example below, you need to use the contents of the specs/workflow-service-schema.json file and specs/workflow-service-openapi.json file to create the ConfigMap:

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

The Hello Service workflow in the example offers two options. You can either create two ConfigMaps, each for one file, to have a clear separation of concerns or group them into one.

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. Navigate into the directory where your resource files are available and create the config map using following command:

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
                                # <CONTENT OF THE FILE>
  workflow-service-openapi.json: # data was removed to save space
                                 # <CONTENT OF THE FILE>

Now you can add reference to this ConfigMap into 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!