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
-
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:
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:
kubectl create configmap service-files --from-file=$(pwd) -n <workflow-namespace>
Replace |
You should have a ConfigMap
with two data entries similar to this one:
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:
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 |
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.
Found an issue?
If you find an issue or any misleading information, please feel free to report it here. We really appreciate it!