Serverless Workflow Validations

Blog: Drools & jBPM Blog

Writing a Serverless Workflow that matches with the specification’s rules and schema can require some documentation reading, which demands a few hours.

To facilitate that, we have implemented a validation mechanism on our Serverless Workflow Editor, that checks your JSON and YAML files against Serverless Workflow specifications schema and also provides some custom validations in addition to it, that will be detailed below.

Requirements

VS Code (1.66.0+)
Kogito Serverless Workflow Editor (0.26.0)

The Serverless Logic Web Tools contains a ready-to-use online version of the Serverless Workflow Editor, where this new feature can be tried by using one of the provided samples or creating a new workflow.

Serverless Workflow language service and validation

The validation mechanism consists of a dedicated language service for Serverless Workflow, which uses existing JSON and YAML language services as a base and is customized on top of it with the Serverless Workflow specification validation. This feature is provided in both Serverless Logic Web Tools and the built-in editor in the Serverless Workflow VS Code extension.

The validated rules include schema validation and some custom validations, which helps in validating extensive Serverless Workflow nodes like functions, states, events etc.

The validation results are highlighted immediately in the editor with a proper message when you hover the error. They can also be seen at the problems section in VS Code or Web Tools.

Create and validate a Serverless Workflow file

Let’s create a fresh Serverless Workflow from scratch and see how validation works.

Create a new file with the ".sw.json” extension. After opening the file in the editor, it will contain an option “Create a Serverless Workflow” at the top. When clicked, it will create a Serverless Workflow specification template, which can also be achieved by using the keyboard shortcut Ctrl + Space. Your workflow can be built on top of this template.

You can also check out some interesting Serverless Workflow examples from the kogito-examples repository.

Schema Validation

The schema validation in Serverless Workflow language service matches the workflow against the schema as per the specification v0.8 released by CNCF. This validation does some strict type checks on every property of the workflow.

Custom Validation

Serverless Workflow Editor offers some custom validations, which validates the values assigned to Serverless Workflow nodes like functions, states, events etc. This check also includes validating refs like eventRefs, functionRefs, subFlowRefs etc, which comes in handy in assigning the correct references to every property. Let us see how the editor implies custom validations with the example of functions node.

Validating Function Node

First let’s understand the FunctionRef definition a bit. FunctionRef definition can have two types, either string or object. If string, it defines the name of the referenced function from the functions array.

"functions": [ 
 {
  "name": "myFunction",
  "operation": "localhost#operation",
  "type": "rest
 }
],
"states": [
    {
        "name": "CheckInbox",
        "type": "operation",
        "actionMode": "sequential",
        "actions": [
            {
                "functionRef": "myFunction"
            }
        ],
        "transition": "SendTextForHighPriority"
    }
]

Similarly, If you need to define parameters in your functionRef definition, you can define it with its object type which has the properties like refName, arguments, selectionSet, invoke.

"functions": [ 
 {
  "name": "checkFundsAvailabe",
  "operation": "localhost#operation",
  "type": "rest
 }
],
"state": [
  {
    "refName": "checkFundsAvailabe",
    "arguments": {
      "account": {
        "id": "${ .accountId }"
      },
      "forAmount": "${ .payment.amount }",
      "insufficientMessage": "The requested amount is not available."
     }
  }
]

The editor automatically does this extensive validation by the time you enter a value in its properties. It checks if the referenced function name is already part of the functions array and displays a warning if it is not present.

Validating other prominent nodes

Similar to the functions node, the editor also validates workflow nodes like Auth, Retries, Subflows, Events, States and others. The type checks of these nodes are done by schema validation, while the references passed are validated by the custom validations implemented in addition to it. The detected errors are highlighted immediately in the editor on both Web Tools and the VS Code extension.