Sub Process Step

Overview

The Sub Process step allows you to call another process definition as a child process within your current workflow. This enables modular process design, code reuse, and complex workflow composition.

Configuration

Input Parameters

Parameter	Type	Required	Description
processName	String	Yes	Name of the process definition to execute
processVersion	Integer	No	Version of the process definition (defaults to latest)
waitForCompletion	Boolean	No	Whether to wait for the subprocess to complete (default: true)
requestId	String	No	Custom request ID for the subprocess
correlationId	String	No	Custom correlation ID for tracking
input	Object	No	Input data to pass to the subprocess

Output

The Sub Process step provides the following output:

Field	Type	Description
subProcessOutput	Object	The output from the executed subprocess
subProcessId	Long	ID of the executed subprocess instance
subProcessRequestId	String	Request ID of the subprocess
subProcessCorrelationId	String	Correlation ID of the subprocess
error	String	Error message if the subprocess fails

Execution Modes

Synchronous Execution (waitForCompletion: true)

When waitForCompletion is true (default), the step waits for the subprocess to complete before continuing:

• Status: Step remains RUNNING until subprocess completes
• Output: Contains the final result from the subprocess
• Use Case: When you need the subprocess result to continue

Asynchronous Execution (waitForCompletion: false)

When waitForCompletion is false, the step starts the subprocess and immediately continues:

• Status: Step immediately becomes COMPLETED
• Output: Contains subprocess metadata but not the final result
• Use Case: Fire-and-forget operations or background tasks

Critical: waitForCompletion Behavior

Important: When waitForCompletion is set to false, the Sub Process step will always mark as successful (COMPLETED) regardless of the actual outcome of the subprocess execution. This means:

• The step status becomes COMPLETED immediately after starting the subprocess
• You won't know if the subprocess succeeded or failed
• The subprocess continues running in the background
• Use this mode only for operations where you don't need to know the result

For most use cases, keep waitForCompletion: true (default) to ensure proper error handling and result validation.

Process Status Handling

The Sub Process step handles different subprocess statuses:

Subprocess Status	Step Status	Description
COMPLETED	COMPLETED	Subprocess finished successfully
REVIEWED	COMPLETED	Subprocess completed and reviewed
TERMINATED	COMPLETED	Subprocess was terminated
RUNNING	RUNNING	Subprocess is still executing
FAILED	FAILED	Subprocess encountered an error

Error Handling

Process Not Found

If the specified process name doesn't exist in the namespace:

{
  "error": "The selected sub process name {processName} does not exist in the namespace : {namespace}"
}

Subprocess Failure

When a subprocess fails, the error is captured in the output:

{
  "subProcessOutput": {
    "error": "Error message from subprocess"
  }
}

Loop Context Support

The Sub Process step supports loop contexts (ForEach, While loops):

• Automatically handles ticket allocation for loop iterations
• Tracks execution state across loop iterations
• Manages subprocess lifecycle within loop boundaries

Authentication and Authorization

• Subprocesses inherit authentication context from the parent process
• User permissions and roles are preserved across process boundaries
• Auth claims are automatically passed to child processes

Examples

Basic Subprocess Call

{
  "type": "SUB_PROCESS",
  "name": "callUserService",
  "input": {
    "processName": "getUserProfile",
    "waitForCompletion": true,
    "input": {
      "userId": "{{ context.input.userId }}",
      "includePreferences": true
    }
  }
}

Asynchronous Subprocess

{
  "type": "SUB_PROCESS",
  "name": "sendNotification",
  "input": {
    "processName": "emailNotification",
    "waitForCompletion": false,
    "input": {
      "recipient": "{{ context.input.email }}",
      "template": "welcome"
    }
  }
}

Dynamic Process Selection

{
  "type": "SUB_PROCESS",
  "name": "dynamicCall",
  "input": {
    "processName": "{{ steps.decideService.output.serviceName }}",
    "processVersion": 2,
    "input": {
      "data": "{{ context.input.payload }}"
    }
  }
}

Best Practices

1. Modular Design: Use subprocesses to break complex workflows into manageable components
2. Error Handling: Always check for errors in subprocess output
3. Version Control: Specify process versions for production stability
4. Performance: Use asynchronous execution for non-critical operations
5. Resource Management: Be mindful of nested subprocess calls to avoid deep call stacks

Use Cases

• API Orchestration: Call different API functions based on authorization
• Microservice Integration: Coordinate multiple service calls
• Workflow Composition: Build complex workflows from simpler components
• Background Processing: Execute long-running tasks asynchronously
• Conditional Logic: Call different processes based on business rules