Chapter 6. OpenShift Serverless Logic overview

An error definition in a workflow includes the name and code parameters. The name provides a short, natural language description of the error, such as wrong parameter. The code helps the implementation identify the error.

The code parameter is mandatory. The engine uses different strategies to map the value to a runtime exception, including fully qualified class name (FQCN), error message, and status code.

During workflow execution, you must handle known errors in the top-level errors property. You can define this property as a string to reference a reusable JSON or YAML file, or as an array to define errors inline in the workflow.

The following example shows how to reference a reusable JSON error definition file:

{
  "errors": "file://documents/reusable/errors.json"
}

The following example shows how to reference a reusable YAML error definition file:

errors: file://documents/reusable/errors.yaml

The following example defines workflow errors inline in a JSON file:

{
  "errors": [
    {
      "name": "Service not found error",
      "code": "404",
      "description": "Server has not found anything matching the provided service endpoint information"
    }
  ]
}

The following example defines workflow errors inline in a YAML file:

errors:
  - name: Service not found error
    code: '404'
    description: Server has not found anything matching the provided service endpoint information

The dataInputSchema parameter validates workflow data input against a defined JSON schema. You should offer dataInputSchema because the system verifies the input before it executes any workflow states.

You can define a dataInputSchema as follows:

"dataInputSchema": {
   "schema": "URL_to_json_schema",
   "failOnValidationErrors": false
}

The schema property uses a URI to specify the path to the JSON schema that validates the workflow data input. You can use a classpath URI, a file path, or an HTTP URL. If you specify a classpath URI, place the JSON schema file in the project resources or another directory in the classpath.

The failOnValidationErrors parameter is optional and controls how the system handles invalid input data. If you do not specify this parameter or set it to true, the system throws an exception and stops execution. If you set it to false, the system continues execution and logs validation errors at the warning (WARN) level.

Output schema definition is applied after workflow execution to verify that the output model has the expected format. It is also useful for Swagger generation purposes.

Similar to Input schema definition, you must specify the URL to the JSON schema, using outputSchema as follows:

"extensions" : [ {
      "extensionid": "workflow-output-schema",
      "outputSchema": {
         "schema" : "URL_to_json_schema",
          "failOnValidationErrors": false
     }
  } ]

The same rules described for dataInputSchema are applicable for schema and failOnValidationErrors. The only difference is that the latter flag is applied after workflow execution.

You can use the sysout function for logging, as shown in the following example:

{
  "functions": [
    {
      "name": "logInfo",
      "type": "custom",
      "operation": "sysout:INFO"
    }
  ]
}

The string after the : is optional and is used to indicate the log level. The possible values are TRACE, DEBUG, INFO, WARN, and ERROR. If the value is not present, INFO is the default.

In the state definition, you can call the same sysout function as shown in the following example:

{
  "states": [
    {
      "name": "myState",
      "type": "operation",
      "actions": [
        {
          "name": "printAction",
          "functionRef": {
            "refName": "logInfo",
            "arguments": {
              "message": "\"Workflow model is \\(.)\""
            }
          }
        }
      ]
    }
  ]
}

In the earlier example, the message argument can be a jq expression or a jq string using interpolation.

OpenShift Serverless Logic supports the java functions within an Apache Maven project, in which you define your workflow service.

The following example shows the declaration of a java function:

{
  "functions": [
    {
      "name": "myFunction",
      "type": "custom",
      "operation": "service:java:com.acme.MyInterfaceOrClass::myMethod"
    }
  ]
}

OpenShift Serverless Logic implements a custom function through the knative-serving add-on to call Knative services. You define a static URI for a Knative service and use it to perform HTTP requests. The system queries the Knative service in the current cluster and translates it into a valid URL.

The following example uses a deployed Knative service:

$ kn service list
NAME                              URL                                                                      LATEST                                  AGE     CONDITIONS   READY   REASON
custom-function-knative-service   http://custom-function-knative-service.default.10.109.169.193.sslip.io   custom-function-knative-service-00001   3h16m   3 OK / 3     True

You can declare a OpenShift Serverless Logic custom function by using the Knative service name, as shown in the following example:

  "functions": [
    {
      "name": "greet",
      "type": "custom",
      "operation": "knative:services.v1.serving.knative.dev/custom-function-knative-service?path=/plainJsonFunction",
    }
  ]

OpenShift Serverless Logic offers the REST custom type as a shortcut. When you use a custom REST function, you specify the HTTP URI to cal and the HTTP method GET, POST, PATCH, or PUT in the function definition by using the operation string. When you call the function, you pass request arguments as you do with an OpenAPI function.

The following example shows the declaration of a rest function:

  {
  "functions": [
    {
      "name": "multiplyAllByAndSum",
      "type": "custom",
      "operation": "rest:post:/numbers/{multiplier}/multiplyByAndSum"
    }
  ]
}

When using the relative endpoints, you must specify the host as a property. The format of the host property is kogito.sw.functions.<function_name>.host. In this example, kogito.sw.functions.multiplyAllByAndSum.host is the host property key. You can override the default port (80) if needed by specifying the kogito.sw.functions.multiplyAllAndSum.port property.

This endpoint expects as body a JSON object whose field numbers is an array of integers, multiplies each item in the array by multiplier, and returns the sum of all the multiplied items.

To configure the maximum duration for a workflow before cancellation, define workflow timeouts. When the system cancels a workflow after the timeout expires, it marks the workflow as finished and removes access through a GET request. As a result, the workflow behaves as if you set the interrupt property to true by default.

You can define workflow timeouts by using the top-level timeouts property. You can specify this property in two formats: string or object.

For example, to cancel the workflow after an hour of execution, use the following configuration:

  {
  "id": "workflow_timeouts",
  "version": "1.0",
  "name": "Workflow Timeouts",
  "description": "Simple workflow to show the workflowExecTimeout working",
  "start": "PrintStartMessage",
  "timeouts": {
    "workflowExecTimeout": "PT1H"
  } ...
}

When you define a state in a workflow, use the timeouts property to set the maximum time allowed to complete that state. If the state exceeds this time, the system marks it as timed out and continues execution from that state. The execution flow depends on the state type. For example, the workflow might move to the next state.

Event-based states can use the sub-property eventTimeout to configure the maximum time to wait for an event to arrive. This is the only property that is supported in current implementation.

Event timeouts support callback state timeout, switch state timeout, and event state timeout.

You can use the Callback state when you need to run an action that calls an external service and wait for an asynchronous response in the form of an event.

After the workflow consumes the response event, it continues execution and typically moves to the next state defined in the transition property.

Because the Callback state halts execution until the event arrives, you can configure an eventTimeout. If the event does not arrive within the configured duration, the workflow continues execution and moves to the next state defined in the transition property.

The following example defines a Callback state with a timeout in JSON format:

{
 "name": "CallbackState",
 "type": "callback",
 "action": {
   "name": "callbackAction",
   "functionRef": {
     "refName": "callbackFunction",
     "arguments": {
       "input": "${\"callback-state-timeouts: \" + $WORKFLOW.instanceId + \" has executed the callbackFunction.\"}"
     }
   }
 },
 "eventRef": "callbackEvent",
 "transition": "CheckEventArrival",
 "onErrors": [
   {
     "errorRef": "callbackError",
     "transition": "FinalizeWithError"
   }
 ],
 "timeouts": {
   "eventTimeout": "PT30S"
 }
}

You can use the Switch state when you need to take an action depending on certain conditions. You can use these conditions based on the workflow data, dataConditions, or on events, eventConditions.

When you use the eventConditions, the workflow execution waits to make a decision until any of the configured events arrives and matches a condition. In this situation, you can configure an event timeout, which controls the maximum time to wait for an event to match the conditions.

If this time expires, the workflow moves to the state defined in the defaultCondition property.

The following example defines a Switch state with a timeout:

{
    "name": "ChooseOnEvent",
    "type": "switch",
    "eventConditions": [
    {
        "eventRef": "visaApprovedEvent",
        "transition": "ApprovedVisa"
    },
    {
        "eventRef": "visaDeniedEvent",
        "transition": "DeniedVisa"
    }
    ],
        "defaultCondition": {
        "transition": "HandleNoVisaDecision"
    },
        "timeouts": {
        "eventTimeout": "PT5S"
    }
}

You can use the Event state to wait for one or more events, run a set of actions, and then continue execution. If the Event state serves as the starting state, the workflow creates a new instance.

You can use the timeouts property in this state to set the maximum time the workflow waits for the configured events to arrive.

If the workflow exceeds this time and does not receive the events, it moves to the next state defined in the transition property. If the state defines an end state, the workflow ends the instance without running any actions.

The following example defines an Event state with a timeout:

{
  "name": "WaitForEvent",
  "type": "event",
  "onEvents": [
    {
      "eventRefs": [
        "event1"
      ],
      "eventDataFilter": {
        "data": "${ \"The event1 was received.\" }",
        "toStateData": "${ .exitMessage }"
      },
      "actions": [
        {
          "name": "printAfterEvent1",
          "functionRef": {
            "refName": "systemOut",
            "arguments": {
              "message": "${\"event-state-timeouts: \" + $WORKFLOW.instanceId + \" executing actions for event1.\"}"
            }
          }
        }
      ]
    },
    {
      "eventRefs": [
        "event2"
      ],
      "eventDataFilter": {
        "data": "${ \"The event2 was received.\" }",
        "toStateData": "${ .exitMessage }"
      },
      "actions": [
        {
          "name": "printAfterEvent2",
          "functionRef": {
            "refName": "systemOut",
            "arguments": {
              "message": "${\"event-state-timeouts: \" + $WORKFLOW.instanceId + \" executing actions for event2.\"}"
            }
          }
        }
      ]
    }
  ],
  "timeouts": {
    "eventTimeout": "PT30S"
  },
  "transition": "PrintExitMessage"
}